build(plugin-market): sync default from MoviePilot-Wiki@4115b7560563

飞牛开启访问码后，需先请求 /c/{访问码} 获得会话凭证，
否则登录接口与图片等资源均返回 404。

- Api 增加 access_code 参数及 verify_access_code()，登录前先校验
- 创建 API 连接时校验访问码，失败则关闭会话
- 图片 Cookies 附带访问码校验凭证，避免代理图片 404

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.coveragerc

@@ -0,0 +1,27 @@
+[run]
+branch = True
+source = app
+omit =
+    app/plugins/*/*
+    app/testing/*
+    app/helper/sites.py
+
+[report]
+show_missing = True
+skip_empty = True
+precision = 2
+exclude_lines =
+    pragma: no cover
+    if TYPE_CHECKING:
+    if __name__ == .__main__.:
+    raise NotImplementedError
+    pass
+
+[html]
+directory = htmlcov
+
+[xml]
+output = coverage.xml
+
+[json]
+output = coverage.json

.dockerignore

@@ -71,6 +71,7 @@ test_*
 
 # Build artifacts
 build/
+.build/
 dist/
 *.egg-info/
 rust/**/target/

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -7,11 +7,13 @@ body:
     attributes:
       value: |
         请说明你希望添加的功能。
+
+        站点适配请求请先按 [站点适配采集说明](https://github.com/jxxghp/MoviePilot/blob/v2/docs/site-adapter-capture.md) 生成脱敏 ZIP，并在下方附加。Issue 及附件是公开内容，提交前必须解压预览四个文件。不要上传 Cookie、Authorization、通行密钥、会话字段或任何原始数据。
   - type: input
     id: version
     attributes:
       label: 当前程序版本
-      description: 目前使用的程序版本
+      description: 目前使用的程序版本；仅提供站点采集文件且未安装 MoviePilot 时填写“不适用”
     validations:
       required: true
   - type: dropdown
@@ -22,6 +24,9 @@ body:
       options:
         - Docker
         - Windows
+        - macOS
+        - Linux
+        - 仅提供站点采集文件
     validations:
       required: true
   - type: dropdown
@@ -32,6 +37,7 @@ body:
       options:
         - 主程序
         - 插件
+        - 站点适配
         - 其他
     validations:
       required: true
@@ -43,6 +49,14 @@ body:
       placeholder: "功能改进"
     validations:
       required: true
+  - type: textarea
+    id: site-adapter-capture
+    attributes:
+      label: 站点适配采集文件
+      description: 站点适配请求必须把采集器生成并人工预览确认过的脱敏 ZIP 拖到这里；Issue 附件公开，严禁附加 Cookie、原始 HTML、HAR 或浏览器网络归档。其他类型请填写“不适用”。
+      placeholder: "将 moviepilot-site-capture-*.zip 拖到这里；非站点适配填写：不适用"
+    validations:
+      required: true
   - type: textarea
     id: references
     attributes:

.github/workflows/beta.yml

@@ -2,6 +2,10 @@ name: MoviePilot Builder Beta
 on:
   workflow_dispatch:
 
+permissions:
+  contents: read
+  packages: write
+
 jobs:
   Docker-build:
     runs-on: ubuntu-latest
@@ -16,6 +20,25 @@ jobs:
           app_version=$(cat version.py |sed -ne "s/APP_VERSION\s=\s'v\(.*\)'/\1/gp")
           echo "app_version=$app_version" >> $GITHUB_ENV
 
+      - name: Checkout Wiki Plugin Market
+        uses: actions/checkout@v4
+        with:
+          repository: jxxghp/MoviePilot-Wiki
+          ref: main
+          path: .build/moviepilot-wiki
+          sparse-checkout: plugin.md
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
+
+      - name: Generate Plugin Market Default
+        id: plugin_market
+        run: |
+          python3 -m scripts.generate_plugin_market_default \
+            --wiki-file .build/moviepilot-wiki/plugin.md \
+            --config-file app/core/config.py
+          wiki_commit=$(git -C .build/moviepilot-wiki rev-parse HEAD)
+          echo "wiki_commit=$wiki_commit" >> "$GITHUB_OUTPUT"
+
       - name: Docker Meta
         id: meta
         uses: docker/metadata-action@v5
@@ -55,6 +78,8 @@ jobs:
             linux/arm64/v8
           push: true
           tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          labels: |
+            ${{ steps.meta.outputs.labels }}
+            org.moviepilot.plugin-market-wiki-revision=${{ steps.plugin_market.outputs.wiki_commit }}
           cache-from: type=gha,scope=moviepilot-docker,version=2
           cache-to: type=gha,scope=moviepilot-docker,mode=max,version=2

.github/workflows/build-v3.yml

@@ -0,0 +1,14 @@
+name: MoviePilot Builder v3
+
+on:
+  workflow_dispatch:
+
+jobs:
+  select-v3:
+    runs-on: ubuntu-latest
+    steps:
+      # GitHub 仅从默认分支登记手动工作流；选择 v3 后会加载 v3 分支的完整构建配置。
+      - name: Require v3 branch
+        run: |
+          echo "::error::请在 Run workflow 中选择 v3 分支"
+          exit 1

.github/workflows/build.yml

@@ -7,6 +7,10 @@ on:
     paths:
       - 'version.py'
 
+permissions:
+  contents: write
+  packages: write
+
 jobs:
   Docker-build:
     runs-on: ubuntu-latest
@@ -23,6 +27,39 @@ jobs:
         run: |
           app_version=$(cat version.py |sed -ne "s/APP_VERSION\s=\s'v\(.*\)'/\1/gp")
           echo "app_version=$app_version" >> $GITHUB_ENV
+          echo "SOURCE_COMMIT=$(git rev-parse HEAD)" >> $GITHUB_ENV
+
+      - name: Checkout Wiki Plugin Market
+        uses: actions/checkout@v4
+        with:
+          repository: jxxghp/MoviePilot-Wiki
+          ref: main
+          path: .build/moviepilot-wiki
+          sparse-checkout: plugin.md
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
+
+      - name: Generate Plugin Market Default
+        id: plugin_market
+        run: |
+          python3 -m scripts.generate_plugin_market_default \
+            --wiki-file .build/moviepilot-wiki/plugin.md \
+            --config-file app/core/config.py
+          wiki_commit=$(git -C .build/moviepilot-wiki rev-parse HEAD)
+          echo "wiki_commit=$wiki_commit" >> "$GITHUB_OUTPUT"
+
+      - name: Create Release Snapshot
+        id: release_snapshot
+        env:
+          WIKI_COMMIT: ${{ steps.plugin_market.outputs.wiki_commit }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add app/core/config.py
+          if ! git diff --cached --quiet; then
+            git commit -m "build(plugin-market): sync default from MoviePilot-Wiki@${WIKI_COMMIT:0:12}"
+          fi
+          echo "release_commit=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
 
       - name: Docker Meta
         id: meta
@@ -65,7 +102,10 @@ jobs:
             linux/arm64/v8
           push: true
           tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          labels: |
+            ${{ steps.meta.outputs.labels }}
+            org.opencontainers.image.revision=${{ steps.release_snapshot.outputs.release_commit }}
+            org.moviepilot.plugin-market-wiki-revision=${{ steps.plugin_market.outputs.wiki_commit }}
           cache-from: type=gha,scope=moviepilot-docker,version=2
           cache-to: type=gha,scope=moviepilot-docker,mode=max,version=2
 
@@ -78,9 +118,9 @@ jobs:
 
           # 使用 || 作为分隔符，同时获取 commit 消息和作者 GitHub 用户名
           if [ -z "$PREVIOUS_TAG" ]; then
-            COMMITS=$(git log --pretty=format:"%s||%an" HEAD)
+            COMMITS=$(git log --pretty=format:"%s||%an" "${SOURCE_COMMIT}")
           else
-            COMMITS=$(git log --pretty=format:"%s||%an" ${PREVIOUS_TAG}..HEAD)
+            COMMITS=$(git log --pretty=format:"%s||%an" "${PREVIOUS_TAG}..${SOURCE_COMMIT}")
           fi
 
           # 分类收集 commit 消息（使用关联数组去重）
@@ -188,6 +228,17 @@ jobs:
           delete_release: true
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Publish Release Tag
+        env:
+          RELEASE_COMMIT: ${{ steps.release_snapshot.outputs.release_commit }}
+        run: |
+          tag_name="v${{ env.app_version }}"
+          if git show-ref --verify --quiet "refs/tags/${tag_name}"; then
+            git tag -d "$tag_name"
+          fi
+          git tag "$tag_name" "$RELEASE_COMMIT"
+          git push origin "refs/tags/${tag_name}"
+
       - name: Generate Release
         uses: softprops/action-gh-release@v2
         with:

.github/workflows/pr-agent.yml

@@ -0,0 +1,52 @@
+name: PR-Agent
+
+on:
+  pull_request_target:
+    # Fork 审查需要目标仓库凭据；该 job 仅通过 GitHub API 读取 PR 内容，不 checkout 或执行 PR 分支代码。
+    types:
+      - opened
+      - reopened
+      - ready_for_review
+      - review_requested
+      - synchronize
+  issue_comment:
+    types:
+      - created
+      - edited
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  pr-agent:
+    if: >-
+      github.event.sender.type != 'Bot' &&
+      (
+        github.event_name == 'pull_request_target' ||
+        (
+          github.event_name == 'issue_comment' &&
+          github.event.issue.pull_request != null &&
+          contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "FIRST_TIME_CONTRIBUTOR"]'), github.event.comment.author_association)
+        )
+      )
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}
+      cancel-in-progress: ${{ github.event_name == 'pull_request_target' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Run PR Review
+        uses: docker://ghcr.io/infinitypacer/pr-review-runner:latest
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          OPENAI_KEY: ${{ secrets.OPENAI_KEY }}
+          OPENAI.API_BASE: ${{ secrets.OPENAI_API_BASE }}
+          PRR_AUTO_REVIEW_SCOPE: all
+          PRR_ALLOWED_ASSOCIATIONS: '["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "FIRST_TIME_CONTRIBUTOR"]'
+          PRR_DISABLED_COMMANDS: '["/improve"]'
+          PRR_SKIP_LABEL: skip pr-agent
+          PRR_SKIP_TITLE_PATTERN: '^(?:\[Auto\]|Auto)'
+          config.response_language: zh-CN

.github/workflows/pylint.yml

@@ -23,24 +23,15 @@ jobs:
       uses: actions/cache@v4
       with:
         path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/requirements.in') }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.in', '**/requirements-dev.in', '**/requirements.txt') }}
         restore-keys: |
           ${{ runner.os }}-pip-
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip setuptools wheel
-        pip install pylint
-        # 安装项目依赖
-        if [ -f requirements.txt ]; then
-          echo "📦 安装 requirements.txt 中的依赖..."
-          pip install -r requirements.txt
-        elif [ -f requirements.in ]; then
-          echo "📦 安装 requirements.in 中的依赖..."
-          pip install -r requirements.in
-        else
-          echo "⚠️ 未找到依赖文件，仅安装 pylint"
-        fi
+        # Pylint 属于开发/静态检查依赖，统一通过 dev 入口安装。
+        pip install -r requirements-dev.in
 
     - name: Verify pylint config
       run: |
@@ -88,4 +79,4 @@ jobs:
       run: |
         echo "🎉 Pylint 检查完成！"
         echo "✅ 没有发现语法错误或严重问题"
-        echo "📊 详细报告已保存为构建工件"
+        echo "📊 详细报告已保存为构建工件"

.github/workflows/site-adapter-collector.yml

@@ -0,0 +1,134 @@
+name: Site Adapter Collector
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Existing release tag to receive collector assets; leave empty for artifacts only
+        required: false
+        type: string
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build ${{ matrix.platform_name }} collector
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform_name: Windows
+            platform_id: windows
+            runner: windows-latest
+            source_name: moviepilot-site-collector.exe
+            asset_name: moviepilot-site-collector-windows.exe
+            artifact_name: site-adapter-collector-windows
+          - platform_name: macOS
+            platform_id: macos
+            runner: macos-latest
+            source_name: moviepilot-site-collector
+            asset_name: MoviePilot-Site-Collector-macOS.zip
+            artifact_name: site-adapter-collector-macos
+          - platform_name: Linux
+            platform_id: linux
+            runner: ubuntu-latest
+            source_name: moviepilot-site-collector
+            asset_name: moviepilot-site-collector-linux
+            artifact_name: site-adapter-collector-linux
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: scripts/site_adapter_collector_requirements.txt
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -r scripts/site_adapter_collector_requirements.txt
+
+      - name: Build single-file collector
+        run: |
+          pyinstaller --clean --noconfirm scripts/site_adapter_collector.spec
+
+      - name: Smoke-test collector
+        env:
+          SOURCE_NAME: ${{ matrix.source_name }}
+        run: |
+          python -c "import os, subprocess; from pathlib import Path; subprocess.run([str((Path('dist') / os.environ['SOURCE_NAME']).resolve()), '--help'], check=True)"
+
+      - name: Package macOS double-click archive
+        if: matrix.platform_id == 'macos'
+        shell: bash
+        env:
+          ASSET_NAME: ${{ matrix.asset_name }}
+          SOURCE_NAME: ${{ matrix.source_name }}
+        run: |
+          package_dir="dist/MoviePilot-Collector"
+          mkdir -p "$package_dir"
+          cp "dist/$SOURCE_NAME" "$package_dir/moviepilot-site-collector-macos"
+          cp scripts/start-site-adapter-collector.command "$package_dir/start-site-adapter-collector.command"
+          chmod +x "$package_dir/moviepilot-site-collector-macos"
+          chmod +x "$package_dir/start-site-adapter-collector.command"
+          cd dist
+          COPYFILE_DISABLE=1 zip -q -r -X "$ASSET_NAME" MoviePilot-Collector
+
+      - name: Rename Windows and Linux collector
+        if: matrix.platform_id != 'macos'
+        env:
+          ASSET_NAME: ${{ matrix.asset_name }}
+          SOURCE_NAME: ${{ matrix.source_name }}
+        run: |
+          python -c "import os; from pathlib import Path; (Path('dist') / os.environ['SOURCE_NAME']).replace(Path('dist') / os.environ['ASSET_NAME'])"
+
+      - name: Generate SHA-256 checksum
+        env:
+          ASSET_NAME: ${{ matrix.asset_name }}
+        run: |
+          python -c "import hashlib, os; from pathlib import Path; path = Path('dist') / os.environ['ASSET_NAME']; path.with_name(path.name + '.sha256').write_text(f'{hashlib.sha256(path.read_bytes()).hexdigest()}  {path.name}\n', encoding='utf-8')"
+
+      - name: Upload collector artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: ${{ matrix.artifact_name }}
+          path: |
+            dist/${{ matrix.asset_name }}
+            dist/${{ matrix.asset_name }}.sha256
+          if-no-files-found: error
+          retention-days: 3
+
+  publish:
+    name: Upload collectors to release
+    if: github.event_name == 'release' || inputs.release_tag != ''
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download collector artifacts
+        uses: actions/download-artifact@v8
+        with:
+          pattern: site-adapter-collector-*
+          path: release-assets
+          merge-multiple: true
+
+      - name: Upload assets to published release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.release_tag }}
+        run: |
+          gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null
+          gh release upload "$RELEASE_TAG" release-assets/* --clobber --repo "$GITHUB_REPOSITORY"

.github/workflows/test.yml

@@ -0,0 +1,70 @@
+name: Unit Tests
+
+on:
+  # 指向 v2 的 PR 与推送都跑全量单测，作为合并门禁
+  pull_request:
+    branches:
+      - v2
+  push:
+    branches:
+      - v2
+  # 允许手动触发
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: unit-tests-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    name: Unit Tests
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.in', '**/requirements-dev.in', '**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          # 单测需要开发/测试依赖；运行时入口 requirements.in 不携带测试与构建辅助工具。
+          pip install -r requirements-dev.in
+
+      - name: Run tests
+        timeout-minutes: 10
+        run: |
+          # tests/run.py 以 pytest 跑 tests 全量；tests/conftest.py 在收集前把 CONFIG_DIR
+          # 指向临时库并建表；CI 额外生成覆盖率报告，便于后续补测和回归分析。
+          python -m coverage erase
+          python -m coverage run tests/run.py
+          python -m coverage report
+          python -m coverage json
+          python -m coverage xml
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: coverage-report
+          path: |
+            coverage.xml
+            coverage.json
+          retention-days: 7

.gitignore

@@ -16,7 +16,7 @@ app/helper/*.pyd
 app/helper/*.bin
 app/plugins/**
 !app/plugins/__init__.py
-config/cookies/**
+config/cookies/
 config/app.env
 config/user.db*
 config/sites/**
@@ -25,13 +25,19 @@ config/logs/
 config/plugins/
 config/temp/
 config/cache/
+config/.cache/
 .runtime/
 public/
 .moviepilot.env
 *.pyc
 *.log
+.coverage
+coverage.xml
+coverage.json
+htmlcov/
 .vscode
 venv
+moviepilot-site-capture-*.zip
 
 # Pylint
 pylint-report.json
@@ -41,3 +47,6 @@ pylint-report.json
 .claude/
 !.claude/*.json
 .claude/settings.local.json
+
+# Superpowers 设计/计划文档（本地协作产物，不纳入仓库）
+docs/superpowers/

AGENTS.md

@@ -41,6 +41,10 @@ Before executing any task, identify the domain and load the corresponding docume
 * **Primary Reference:** `docs/rules/11-quality-and-security.md`
 * **Required Constraints:** All code changes must pass the relevant pytest tests and pylint checks. Dependency changes require a passing safety scan.
 
+### Testing
+* **Primary Reference:** `docs/testing.md`
+* **Required Constraints:** pytest is the only runner; `tests/conftest.py` isolates each run to a temporary `CONFIG_DIR`. Tests must not touch the real database, network, or external services (TMDB, LLM catalogs, downloaders, media servers, MP server) — mock at the boundary or replay recorded responses; the bar is zero real outbound traffic. Tests must restore any process-level state they stub (`sys.modules`, singletons, caches, settings). New tests must be pytest-native (function + `assert` + fixtures); do not add new `unittest.TestCase`. Convert existing `TestCase` files to pytest-native opportunistically when you modify them. Before opening a PR to `v2`, run the full suite locally (`python tests/run.py`) and confirm it is green with zero real network calls; the `.github/workflows/test.yml` gate runs the same suite on every PR/push to `v2`.
+
 ### Commands and Development Workflow
 * **Primary Reference:** `docs/rules/03-commands.md`
 * **Required Constraints:** Only suggest or execute commands documented in that file. Do not assume tool defaults or global flags.

README.md

@@ -1,4 +1,3 @@
-
 # MoviePilot
 
 简体中文 | [English](README_EN.md)
@@ -12,66 +11,57 @@
 ![Docker Pulls V2](https://img.shields.io/docker/pulls/jxxghp/moviepilot-v2?style=for-the-badge)
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20Synology-blue?style=for-the-badge)
 
-
 基于 [NAStool](https://github.com/NAStool/nas-tools) 部分代码重新设计，聚焦自动化核心需求，减少问题同时更易于扩展和维护。
 
 # 仅用于学习交流使用，请勿在任何国内平台宣传该项目！
 
 发布频道：https://t.me/moviepilot_channel
 
-
 ## 主要特性
 
-- 前后端分离，基于FastApi + Vue3。
-- 聚焦核心需求，简化功能和设置，部分设置项可直接使用默认值。
-- 重新设计了用户界面，更加美观易用。
-
+- 聚焦影视自动化的核心流程：订阅、搜索、下载、整理、刮削、媒体库刷新与消息通知。
+- 前后端分离，后端基于 FastAPI，前端基于 Vue 3，部署和扩展边界更清晰。
+- 支持下载器、媒体服务器、元数据源、消息渠道、插件、工作流和 AI Agent 等能力组合。
+- 更完整的功能介绍、截图和使用入口见官网：https://movie-pilot.org
 
 ## 安装使用
 
-官方Wiki：https://wiki.movie-pilot.org
+推荐优先使用 Docker 部署，常用镜像包括 `jxxghp/moviepilot-v2` 和 `jxxghp/moviepilot`。Compose 示例、环境变量、目录映射和升级方式以官方 Wiki 为准：
 
+- 官方 Wiki：https://wiki.movie-pilot.org
+- PostgreSQL 部署说明：[docs/postgresql-setup.md](docs/postgresql-setup.md)
 
-## 本地 CLI
-
-一键安装运行脚本：
+也可以使用本地 CLI 以源码模式安装和管理 MoviePilot：
 
 ```shell
 curl -fsSL https://raw.githubusercontent.com/jxxghp/MoviePilot/v2/scripts/bootstrap-local.sh | bash
 ```
 
-使用 `moviepilot` 命令管理MoviePilot，完整 CLI 文档：[`docs/cli.md`](docs/cli.md)
+安装完成后使用 `moviepilot` 命令完成初始化、启动、停止、更新和配置查看。完整命令见 [docs/cli.md](docs/cli.md)。
 
+## Agent
+
+1. MoviePilot 自带智能体能力，可在完成模型配置后，通过自然语言调用系统工具，辅助完成搜索、订阅、下载、整理、排障等管理任务。
+2. 其它智能体可以导入本仓库的 `skills/` 目录以获得 MoviePilot 操作能力；支持 `skills` CLI 的环境可使用：
+
+   ```shell
+   npx skills add https://github.com/jxxghp/MoviePilot
+   ```
+
+   内置 Skills 列表见 [skills/](skills/)，自定义 Skill 可参考 [skills/create-moviepilot-skill/SKILL.md](skills/create-moviepilot-skill/SKILL.md)。
+3. 其它 MCP 客户端可以通过 MoviePilot 的 MCP 端点 `/api/v1/mcp` 调用工具，认证方式、客户端配置和工具 API 见 [docs/mcp-api.md](docs/mcp-api.md)。
 
-## 为 AI Agent 添加 Skills
-```shell
-npx skills add https://github.com/jxxghp/MoviePilot
-```
 
 ## 参与开发
 
-API文档：https://api.movie-pilot.org
+开发前请先阅读仓库规则和本地环境说明，保持变更聚焦，通过测试后再提交 PR。常用入口：
 
-MCP工具API文档：详见 [docs/mcp-api.md](docs/mcp-api.md)
-
-开发环境准备与本地源码运行说明：[`docs/development-setup.md`](docs/development-setup.md)
-
-本地开发默认通过 PyPI 依赖安装 Rust 加速扩展；扩展未安装或 `RUST_ACCEL=false` 时会自动使用 Python 实现：
-
-```shell
-python -m pip install moviepilot-rust
-python -c "from app.utils import rust_accel; print(rust_accel.is_available())"
-```
-
-如果输出 `True`，说明当前开发环境已经加载 `moviepilot_rust`。Rust 源码和打包发布流程在 [MoviePilot-Rust](https://github.com/jxxghp/MoviePilot-Rust) 仓库维护。
-
-需要本地评估 Rust 加速效果时，可运行：
-
-```shell
-python scripts/benchmark_rust_accel.py --loops 20 --repeat 5
-```
-
-插件开发说明：<https://wiki.movie-pilot.org/zh/plugindev>
+- 文档规则入口：[docs/rules/README.md](docs/rules/README.md)
+- 开发环境与本地源码运行：[docs/development-setup.md](docs/development-setup.md)
+- 测试说明：[docs/testing.md](docs/testing.md)
+- 新站点适配采集与 Feature Request 提交：[docs/site-adapter-capture.md](docs/site-adapter-capture.md)
+- REST API 文档：https://api.movie-pilot.org
+- 插件开发说明：https://wiki.movie-pilot.org/zh/plugindev
 
 ## 相关项目
 
@@ -79,6 +69,7 @@ python scripts/benchmark_rust_accel.py --loops 20 --repeat 5
 - [MoviePilot-Resources](https://github.com/jxxghp/MoviePilot-Resources)
 - [MoviePilot-Plugins](https://github.com/jxxghp/MoviePilot-Plugins)
 - [MoviePilot-Server](https://github.com/jxxghp/MoviePilot-Server)
+- [MoviePilot-Rust](https://github.com/jxxghp/MoviePilot-Rust)
 - [MoviePilot-Wiki](https://github.com/jxxghp/MoviePilot-Wiki)
 
 ## 免责申明

README_EN.md

@@ -17,44 +17,50 @@ Redesigned from parts of [NAStool](https://github.com/NAStool/nas-tools), with a
 
 Release channel: https://t.me/moviepilot_channel
 
-
 ## Key Features
 
-- Frontend/backend separation based on FastApi + Vue3.
-- Focuses on core needs, simplifies features and settings, and allows some options to work well with sensible defaults.
-- Reworked user interface for a cleaner and more practical experience.
+- Focuses on the core media automation flow: subscriptions, search, downloads, file organization, scraping, media server refresh, and notifications.
+- Uses a separated backend/frontend architecture: FastAPI for the backend and Vue 3 for the frontend.
+- Connects download clients, media servers, metadata providers, message channels, plugins, workflows, and AI Agent capabilities.
+- For feature details, screenshots, and product entry points, see https://movie-pilot.org
 
+## Installation and Usage
 
-## Installation
+Docker is the recommended deployment model. Common images include `jxxghp/moviepilot-v2` and `jxxghp/moviepilot`. Compose examples, environment variables, volume mappings, and upgrade notes are maintained in the official wiki:
 
-Official wiki: https://wiki.movie-pilot.org
+- Official wiki: https://wiki.movie-pilot.org
+- PostgreSQL setup: [docs/postgresql-setup.md](docs/postgresql-setup.md)
 
-
-## Local CLI
-
-One-command bootstrap script:
+MoviePilot can also be installed and managed from source with the local CLI:
 
 ```shell
 curl -fsSL https://raw.githubusercontent.com/jxxghp/MoviePilot/v2/scripts/bootstrap-local.sh | bash
 ```
 
-Manage MoviePilot with the `moviepilot` command. Full CLI documentation: [`docs/cli.md`](docs/cli.md)
+After installation, use the `moviepilot` command for initialization, service management, updates, and configuration. See [docs/cli.md](docs/cli.md) for the full command reference.
 
+## Agent
 
-## Add Skills for AI Agents
-```shell
-npx skills add https://github.com/jxxghp/MoviePilot
-```
+1. MoviePilot includes a built-in AI Agent. After model configuration, it can call system tools through natural language to help with search, subscriptions, downloads, organization, diagnostics, and other management tasks.
+2. Other agents can import the repository `skills/` directory to gain MoviePilot operation capabilities. Environments that support the `skills` CLI can use:
+
+   ```shell
+   npx skills add https://github.com/jxxghp/MoviePilot
+   ```
+
+   Built-in skills live in [skills/](skills/). For custom skill authoring, see [skills/create-moviepilot-skill/SKILL.md](skills/create-moviepilot-skill/SKILL.md).
+3. Other MCP clients can call MoviePilot tools through `/api/v1/mcp`. Authentication, client configuration, and tool APIs are documented in [docs/mcp-api.md](docs/mcp-api.md).
 
 ## Development
 
-API documentation: https://api.movie-pilot.org
+Before contributing, read the repository rules and local environment guide, keep changes focused, and validate them before opening a PR. Useful entry points:
 
-MCP tool API documentation: see [docs/mcp-api.md](docs/mcp-api.md)
-
-Development environment setup and local source-run guide: [`docs/development-setup.md`](docs/development-setup.md)
-
-Plugin development guide: <https://wiki.movie-pilot.org/zh/plugindev>
+- Rule index: [docs/rules/README.md](docs/rules/README.md)
+- Development setup and local source run: [docs/development-setup.md](docs/development-setup.md)
+- Testing guide: [docs/testing.md](docs/testing.md)
+- New site adapter capture and Feature Request submission: [docs/site-adapter-capture.md](docs/site-adapter-capture.md)
+- REST API documentation: https://api.movie-pilot.org
+- Plugin development guide: https://wiki.movie-pilot.org/zh/plugindev
 
 ## Related Projects
 
@@ -62,6 +68,7 @@ Plugin development guide: <https://wiki.movie-pilot.org/zh/plugindev>
 - [MoviePilot-Resources](https://github.com/jxxghp/MoviePilot-Resources)
 - [MoviePilot-Plugins](https://github.com/jxxghp/MoviePilot-Plugins)
 - [MoviePilot-Server](https://github.com/jxxghp/MoviePilot-Server)
+- [MoviePilot-Rust](https://github.com/jxxghp/MoviePilot-Rust)
 - [MoviePilot-Wiki](https://github.com/jxxghp/MoviePilot-Wiki)
 
 ## Disclaimer

app/__init__.py

@@ -0,0 +1,15 @@
+import warnings
+
+
+def _filter_third_party_startup_warnings() -> None:
+    """
+    过滤第三方库在新版 Python 下产生的已知无害启动警告。
+    """
+    warnings.filterwarnings(
+        "ignore",
+        message=r"invalid escape sequence '\\&'",
+        category=SyntaxWarning,
+    )
+
+
+_filter_third_party_startup_warnings()

app/agent/callback/__init__.py

@@ -261,6 +261,12 @@ class StreamingHandler:
             tool_message=tool_message,
             tool_kwargs=tool_kwargs or {},
         )
+        target_values = []
+        if isinstance(target, (list, tuple, set)):
+            target_values = [item for item in target if item]
+        elif target:
+            target_values = [target]
+
         with self._lock:
             bucket = self._pending_tool_stats.setdefault(
                 category,
@@ -269,9 +275,30 @@ class StreamingHandler:
                     "targets": set(),
                 },
             )
-            bucket["count"] += 1
-            if target:
-                bucket["targets"].add(str(target))
+            if category == "subagent" and target_values:
+                bucket["count"] += len(target_values)
+            else:
+                bucket["count"] += 1
+            for target_value in target_values:
+                bucket["targets"].add(str(target_value))
+
+    @staticmethod
+    def _extract_subagent_targets(tool_kwargs: dict[str, Any]) -> list[str]:
+        """提取子代理工具请求中的目标子代理类型。"""
+        tasks = tool_kwargs.get("tasks")
+        if not isinstance(tasks, list):
+            subagent_type = tool_kwargs.get("subagent_type")
+            return [str(subagent_type)] if subagent_type else []
+
+        targets = []
+        for task in tasks:
+            if isinstance(task, dict):
+                subagent_type = task.get("subagent_type")
+            else:
+                subagent_type = getattr(task, "subagent_type", None)
+            if subagent_type:
+                targets.append(str(subagent_type))
+        return targets
 
     def flush_pending_tool_summary(self) -> str:
         """
@@ -288,11 +315,19 @@ class StreamingHandler:
         tool_name: str,
         tool_message: Optional[str],
         tool_kwargs: dict[str, Any],
-    ) -> tuple[str, Optional[str]]:
+    ) -> tuple[str, Optional[Any]]:
         tool_name = (tool_name or "").strip().lower()
         tool_message = (tool_message or "").strip()
         tool_message_lower = tool_message.lower()
 
+        if tool_name == "skill":
+            return "skill", tool_kwargs.get("name")
+        if tool_name == "query_activity_log":
+            return "activity_log", tool_kwargs.get("keyword") or tool_kwargs.get("date")
+        if tool_name == "subagent_task":
+            return "subagent", StreamingHandler._extract_subagent_targets(tool_kwargs)
+        if tool_name == "task":
+            return "subagent", tool_kwargs.get("subagent_type")
         if tool_name == "read_file":
             return "file_read", tool_kwargs.get("file_path")
         if tool_name in {"write_file", "edit_file"}:
@@ -367,7 +402,7 @@ class StreamingHandler:
         parts = []
         for category, bucket in self._pending_tool_stats.items():
             value = bucket["count"]
-            if category in {"file_read", "file_write", "directory", "web_browse"} and bucket["targets"]:
+            if category in {"file_read", "file_write", "directory", "web_browse", "skill"} and bucket["targets"]:
                 value = len(bucket["targets"])
             part = self._format_tool_stat(category, value)
             if part:
@@ -404,10 +439,16 @@ class StreamingHandler:
             return f"执行了 {count} 条命令"
         if category == "data_query":
             return f"查询了 {count} 次数据"
+        if category == "skill":
+            return f"查询了 {count} 个技能说明"
+        if category == "activity_log":
+            return f"查询了 {count} 次活动日志"
         if category == "action":
             return f"执行了 {count} 次操作"
         if category == "interaction":
             return f"发起了 {count} 次交互"
+        if category == "subagent":
+            return f"已调用 {count} 个子代理"
         return f"调用了 {count} 次工具"
 
     def _can_stream(self) -> bool:
@@ -495,6 +536,7 @@ class StreamingHandler:
                         original_chat_id=self._original_chat_id,
                         title=self._title,
                         text=current_text,
+                        save_history=False,
                     ),
                 )
                 if response and response.success and response.message_id:
@@ -540,6 +582,7 @@ class StreamingHandler:
                                 original_chat_id=self._original_chat_id,
                                 title=self._title,
                                 text=current_text,
+                                save_history=False,
                             ),
                         )
                         if response and response.success and response.message_id:

app/agent/defaults/subagents/download-diagnostician/SUBAGENT.md

@@ -0,0 +1,20 @@
+---
+version: 1
+subagent_id: download-diagnostician
+label: 下载诊断
+description: Download and transfer diagnosis subagent for downloaders, download tasks, transfer history, and library status.
+include_tags:
+  - download
+  - transfer
+  - library
+  - directory
+  - file
+  - media
+exclude_tags:
+  - write
+  - message
+  - user_interaction
+---
+# SUBAGENT
+
+You specialize in downloaders, download tasks, transfer history, directory settings, and library ingestion state.

app/agent/defaults/subagents/general-purpose/SUBAGENT.md

@@ -0,0 +1,35 @@
+---
+version: 1
+subagent_id: general-purpose
+label: 通用调查
+description: General read-only investigation subagent for cross-domain MoviePilot analysis and execution recommendations.
+include_tags:
+  - media
+  - resource
+  - site
+  - subscription
+  - download
+  - library
+  - transfer
+  - system
+  - settings
+  - plugin
+  - workflow
+  - scheduler
+  - file
+  - directory
+  - web
+  - command
+  - filter_rule
+  - persona
+  - slash_command
+  - recommendation
+  - metadata
+exclude_tags:
+  - write
+  - message
+  - user_interaction
+---
+# SUBAGENT
+
+You specialize in synthesizing media, site, subscription, download, and system status signals.

app/agent/defaults/subagents/media-researcher/SUBAGENT.md

@@ -0,0 +1,19 @@
+---
+version: 1
+subagent_id: media-researcher
+label: 媒体研究
+description: Media research subagent for title recognition, people, episodes, metadata, and library existence checks.
+include_tags:
+  - media
+  - library
+  - recommendation
+  - metadata
+  - web
+exclude_tags:
+  - write
+  - message
+  - user_interaction
+---
+# SUBAGENT
+
+You specialize in media identity resolution, metadata validation, person credits, and library status analysis.

app/agent/defaults/subagents/moviepilot-explorer/SUBAGENT.md

@@ -0,0 +1,19 @@
+---
+version: 1
+subagent_id: moviepilot-explorer
+label: 代码探索
+description: MoviePilot exploration subagent for source-code inspection, configuration structure analysis, logs, and code-level troubleshooting clues.
+include_tags:
+  - system
+  - settings
+  - file
+  - directory
+  - command
+exclude_tags:
+  - write
+  - message
+  - user_interaction
+---
+# SUBAGENT
+
+You specialize in MoviePilot source-code structure, local configuration files, directory layout, logs or read-only command output, and code-level root-cause troubleshooting. Prefer reading relevant code paths before judging behavior, and distinguish code/config evidence from runtime system state.

app/agent/defaults/subagents/resource-searcher/SUBAGENT.md

@@ -0,0 +1,18 @@
+---
+version: 1
+subagent_id: resource-searcher
+label: 资源搜索
+description: Site and resource search subagent for site checks, torrent search, and resource quality analysis.
+include_tags:
+  - resource
+  - site
+  - web
+  - media
+exclude_tags:
+  - write
+  - message
+  - user_interaction
+---
+# SUBAGENT
+
+You specialize in site status, site user data, torrent search results, and resource quality judgment.

app/agent/defaults/subagents/subscription-analyst/SUBAGENT.md

@@ -0,0 +1,18 @@
+---
+version: 1
+subagent_id: subscription-analyst
+label: 订阅分析
+description: Subscription analysis subagent for subscriptions, history, filter rules, and custom identifiers.
+include_tags:
+  - subscription
+  - filter_rule
+  - settings
+  - media
+exclude_tags:
+  - write
+  - message
+  - user_interaction
+---
+# SUBAGENT
+
+You specialize in current subscription state, subscription history, filter rules, and subscription optimization suggestions.

app/agent/defaults/subagents/system-diagnostician/SUBAGENT.md

@@ -0,0 +1,25 @@
+---
+version: 1
+subagent_id: system-diagnostician
+label: 系统诊断
+description: System diagnosis subagent for read-only inspection of settings, schedulers, workflows, plugins, directories, and command output.
+include_tags:
+  - system
+  - settings
+  - plugin
+  - workflow
+  - scheduler
+  - file
+  - directory
+  - web
+  - command
+  - persona
+  - slash_command
+exclude_tags:
+  - write
+  - message
+  - user_interaction
+---
+# SUBAGENT
+
+You specialize in settings, plugins, scheduled tasks, workflows, directories, and read-only command diagnostics.

app/agent/llm/capability.py

@@ -670,6 +670,11 @@ class AgentCapabilityManager:
     def _normalize_provider_name(provider: Optional[str]) -> str:
         return (provider or "openai").strip().lower()
 
+    @staticmethod
+    def _get_provider_log_name(provider: AudioCapabilityProvider) -> str:
+        provider_name = getattr(provider, "name", None)
+        return provider_name if isinstance(provider_name, str) else provider.__class__.__name__
+
     @classmethod
     def get_audio_provider(cls, mode: str) -> Optional[AudioCapabilityProvider]:
         provider_name = cls._normalize_provider_name(
@@ -686,7 +691,9 @@ class AgentCapabilityManager:
     @staticmethod
     def supports_image_input() -> bool:
         """当前 Agent 是否启用图片输入能力。"""
-        return bool(settings.LLM_SUPPORT_IMAGE_INPUT)
+        from app.agent.llm.helper import LLMHelper
+
+        return LLMHelper.supports_image_input()
 
     @staticmethod
     def supports_audio_input() -> bool:
@@ -714,17 +721,45 @@ class AgentCapabilityManager:
 
     @classmethod
     def transcribe_audio(cls, content: bytes, filename: str = "input.ogg") -> Optional[str]:
+        """将语音文件内容转写为文字，并记录能力调用日志。"""
         provider = cls.get_audio_provider("input")
         if not provider or not cls.is_audio_input_available():
+            logger.info("语音转文字跳过：音频输入能力未启用或 provider 不可用")
             return None
-        return provider.transcribe_audio(content=content, filename=filename)
+        provider_name = cls._get_provider_log_name(provider)
+        logger.info(
+            f"语音转文字开始：provider={provider_name}, filename={filename}, "
+            f"bytes={len(content) if content else 0}"
+        )
+        transcript = provider.transcribe_audio(content=content, filename=filename)
+        if transcript:
+            logger.info(
+                f"语音转文字完成：provider={provider_name}, filename={filename}, "
+                f"text_len={len(transcript)}"
+            )
+        else:
+            logger.info(
+                f"语音转文字无结果：provider={provider_name}, filename={filename}"
+            )
+        return transcript
 
     @classmethod
     def synthesize_speech(cls, text: str) -> Optional[Path]:
+        """将文字合成为语音文件，并记录能力调用日志。"""
         provider = cls.get_audio_provider("output")
         if not provider or not cls.is_audio_output_available():
+            logger.info("文字转语音跳过：音频输出能力未启用或 provider 不可用")
             return None
-        return provider.synthesize_speech(text=text)
+        provider_name = cls._get_provider_log_name(provider)
+        logger.info(
+            f"文字转语音开始：provider={provider_name}, text_len={len(text) if text else 0}"
+        )
+        output_path = provider.synthesize_speech(text=text)
+        if output_path:
+            logger.info(f"文字转语音完成：provider={provider_name}, path={output_path}")
+        else:
+            logger.info(f"文字转语音无结果：provider={provider_name}")
+        return output_path
 
     @classmethod
     def resolve_reply_mode(cls, channel: Optional[str], source: Optional[str]) -> str:
@@ -734,29 +769,61 @@ class AgentCapabilityManager:
         return cls.REPLY_MODE_TEXT
 
     @classmethod
-    def supports_native_voice_reply(
-        cls, channel: Optional[str], source: Optional[str]
-    ) -> bool:
-        """判断当前渠道是否支持原生语音消息发送。"""
+    def _parse_message_channel(cls, channel: Optional[Any]):
+        """将渠道入参归一化为消息渠道枚举。"""
         if not channel:
+            return None
+
+        from app.schemas.types import MessageChannel
+
+        if isinstance(channel, MessageChannel):
+            return channel
+
+        channel_text = str(channel).strip()
+        if not channel_text:
+            return None
+        lowered_channel = channel_text.lower()
+        for channel_item in MessageChannel:
+            aliases = {
+                channel_item.value.lower(),
+                channel_item.name.lower(),
+                f"{MessageChannel.__name__}.{channel_item.name}".lower(),
+            }
+            if lowered_channel in aliases:
+                return channel_item
+        return None
+
+    @staticmethod
+    def _is_wechat_app_mode(source: Optional[str]) -> bool:
+        """判断企业微信来源是否为自建应用模式。"""
+        if not source:
             return False
 
         from app.helper.service import ServiceConfigHelper
-        from app.schemas.types import MessageChannel
 
-        try:
-            channel_enum = MessageChannel(channel)
-        except (TypeError, ValueError):
-            return False
-
-        if channel_enum == MessageChannel.Telegram:
-            return True
-        if channel_enum != MessageChannel.Wechat:
-            return False
-
-        # 企业微信 bot 模式不支持发送语音，只有应用模式可用。
         for config in ServiceConfigHelper.get_notification_configs():
             if config.name != source:
                 continue
             return (config.config or {}).get("WECHAT_MODE", "app") != "bot"
         return False
+
+    @classmethod
+    def supports_native_voice_reply(
+            cls, channel: Optional[str], source: Optional[str]
+    ) -> bool:
+        """判断当前渠道是否支持原生语音消息发送。"""
+        from app.schemas.message import ChannelCapability, ChannelCapabilityManager
+        from app.schemas.types import MessageChannel
+
+        channel_enum = cls._parse_message_channel(channel)
+        if not channel_enum:
+            return False
+
+        if not ChannelCapabilityManager.supports_capability(
+                channel_enum, ChannelCapability.AUDIO_OUTPUT
+        ):
+            return False
+
+        if channel_enum == MessageChannel.Wechat:
+            return cls._is_wechat_app_mode(source)
+        return True

app/agent/llm/server_tools.py

@@ -0,0 +1,249 @@
+"""LLM 服务端工具能力注册与解析。"""
+
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from typing import Any, Optional
+
+
+WEB_SEARCH_MODES = frozenset({"local", "builtin", "auto", "disabled"})
+
+
+class ServerToolUnavailableError(ValueError):
+    """表示用户强制选择了当前模型不可用的服务端工具。"""
+
+    def __init__(self, *, provider: str, model: str, tool_id: str) -> None:
+        """初始化服务端工具不可用异常。"""
+        self.provider = provider
+        self.model = model
+        self.tool_id = tool_id
+        super().__init__(
+            f"当前模型 {provider}/{model} 或接口地址不支持服务端联网搜索，"
+            "请改用“自动”或“MoviePilot 本地搜索”"
+        )
+
+
+@dataclass(frozen=True)
+class ServerToolCapability:
+    """描述一个模型可用的服务端工具能力。"""
+
+    tool_id: str
+    provider_ids: tuple[str, ...]
+    model_patterns: tuple[str, ...]
+    required_api_protocol: str
+    client_adapter: str
+    tool_definition: dict[str, Any]
+    base_url_patterns: tuple[str, ...] = ()
+    match_without_base_url: bool = True
+
+    def matches(self, provider: str, model: str, base_url: Optional[str] = None) -> bool:
+        """判断给定 provider/model 是否匹配当前能力。"""
+        normalized_provider = str(provider or "").strip().lower()
+        normalized_model = str(model or "").strip().lower().removeprefix("models/")
+        normalized_base_url = str(base_url or "").strip().lower()
+        return (
+            normalized_provider in self.provider_ids
+            and any(fnmatch(normalized_model, pattern) for pattern in self.model_patterns)
+            and (
+                (not normalized_base_url and self.match_without_base_url)
+                or not self.base_url_patterns
+                or any(
+                    pattern in normalized_base_url
+                    for pattern in self.base_url_patterns
+                )
+            )
+        )
+
+    def serialize(self) -> dict[str, Any]:
+        """返回供 API 与前端使用的能力元数据。"""
+        return {
+            "id": self.tool_id,
+            "required_api_protocol": self.required_api_protocol,
+            "client_adapter": self.client_adapter,
+        }
+
+
+@dataclass(frozen=True)
+class ServerToolResolution:
+    """记录本次联网搜索模式解析后的执行策略。"""
+
+    mode: str
+    use_local_web_search: bool
+    server_tools: tuple[dict[str, Any], ...] = ()
+    client_adapter: Optional[str] = None
+    required_api_protocol: Optional[str] = None
+    available: bool = False
+    reason: Optional[str] = None
+
+
+class ServerToolRegistry:
+    """集中注册模型服务端工具，并解析通用执行策略。"""
+
+    _CAPABILITIES = (
+        ServerToolCapability(
+            tool_id="web_search",
+            provider_ids=("chatgpt",),
+            model_patterns=("gpt-5*", "gpt-4.1*", "o4-mini*"),
+            base_url_patterns=("api.openai.com",),
+            required_api_protocol="responses",
+            client_adapter="openai_responses",
+            tool_definition={"type": "web_search"},
+        ),
+        ServerToolCapability(
+            tool_id="web_search",
+            provider_ids=("openai",),
+            model_patterns=("gpt-5*", "gpt-4.1*", "o4-mini*"),
+            base_url_patterns=("api.openai.com",),
+            required_api_protocol="responses",
+            client_adapter="openai_responses",
+            tool_definition={"type": "web_search"},
+            match_without_base_url=False,
+        ),
+        ServerToolCapability(
+            tool_id="web_search",
+            provider_ids=("anthropic",),
+            model_patterns=(
+                "claude-opus-4*",
+                "claude-sonnet-4*",
+                "claude-haiku-4*",
+                "claude-opus-5*",
+                "claude-sonnet-5*",
+                "claude-haiku-5*",
+                "claude-fable-5*",
+                "claude-mythos-5*",
+            ),
+            base_url_patterns=("api.anthropic.com",),
+            required_api_protocol="native",
+            client_adapter="anthropic_native",
+            tool_definition={
+                "type": "web_search_20250305",
+                "name": "web_search",
+            },
+        ),
+        ServerToolCapability(
+            tool_id="web_search",
+            provider_ids=("google",),
+            model_patterns=("gemini-3*", "gemini-2.5*", "gemini-2.0-flash*"),
+            required_api_protocol="native",
+            client_adapter="google_native",
+            tool_definition={"google_search": {}},
+        ),
+        ServerToolCapability(
+            tool_id="web_search",
+            provider_ids=("xai",),
+            model_patterns=("grok-4.5*",),
+            base_url_patterns=("api.x.ai",),
+            required_api_protocol="responses",
+            client_adapter="openai_responses",
+            tool_definition={"type": "web_search"},
+        ),
+        ServerToolCapability(
+            tool_id="web_search",
+            provider_ids=("deepseek",),
+            model_patterns=("deepseek-v4-flash",),
+            base_url_patterns=("api.deepseek.com",),
+            required_api_protocol="responses",
+            client_adapter="openai_responses",
+            tool_definition={"type": "web_search"},
+        ),
+    )
+
+    @classmethod
+    def normalize_web_search_mode(cls, mode: Optional[str]) -> str:
+        """规范化联网搜索模式，未知值回退为本地搜索。"""
+        normalized = str(mode or "local").strip().lower()
+        return normalized if normalized in WEB_SEARCH_MODES else "local"
+
+    @classmethod
+    def get_capability(
+        cls,
+        *,
+        provider: str,
+        model: str,
+        base_url: Optional[str] = None,
+        tool_id: str,
+    ) -> Optional[ServerToolCapability]:
+        """查找指定模型的服务端工具能力。"""
+        return next(
+            (
+                capability
+                for capability in cls._CAPABILITIES
+                if capability.tool_id == tool_id
+                and capability.matches(provider, model, base_url)
+            ),
+            None,
+        )
+
+    @classmethod
+    def list_capabilities(
+            cls,
+            *,
+            provider: str,
+            model: str,
+            base_url: Optional[str] = None,
+    ) -> list[dict[str, Any]]:
+        """列出指定模型可用的服务端工具能力。"""
+        return [
+            capability.serialize()
+            for capability in cls._CAPABILITIES
+            if capability.matches(provider, model, base_url)
+        ]
+
+    @classmethod
+    def resolve_web_search(
+        cls,
+        *,
+        provider: str,
+        model: str,
+        mode: Optional[str],
+        api_protocol: Optional[str],
+        base_url: Optional[str] = None,
+    ) -> ServerToolResolution:
+        """解析联网搜索应使用本地工具还是模型服务端工具。"""
+        normalized_mode = cls.normalize_web_search_mode(mode)
+        normalized_protocol = str(api_protocol or "auto").strip().lower()
+        capability = cls.get_capability(
+            provider=provider,
+            model=model,
+            base_url=base_url,
+            tool_id="web_search",
+        )
+
+        if normalized_mode == "disabled":
+            return ServerToolResolution(
+                mode=normalized_mode,
+                use_local_web_search=False,
+                reason="web_search_disabled",
+            )
+        if normalized_mode == "local":
+            return ServerToolResolution(
+                mode=normalized_mode,
+                use_local_web_search=True,
+                reason="local_web_search_selected",
+            )
+        if capability is None:
+            return ServerToolResolution(
+                mode=normalized_mode,
+                use_local_web_search=normalized_mode == "auto",
+                reason="builtin_web_search_unavailable",
+            )
+        if (
+            normalized_mode == "auto"
+            and normalized_protocol == "chat_completions"
+            and capability.required_api_protocol == "responses"
+        ):
+            return ServerToolResolution(
+                mode=normalized_mode,
+                use_local_web_search=True,
+                available=True,
+                reason="chat_completions_uses_local_fallback",
+            )
+
+        return ServerToolResolution(
+            mode=normalized_mode,
+            use_local_web_search=False,
+            server_tools=(dict(capability.tool_definition),),
+            client_adapter=capability.client_adapter,
+            required_api_protocol=capability.required_api_protocol,
+            available=True,
+            reason="builtin_web_search_selected",
+        )

app/agent/mcp.py

@@ -0,0 +1,600 @@
+"""Agent 外部 MCP 客户端与配置管理。"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import re
+import uuid
+from dataclasses import dataclass
+from typing import Any, Optional
+from urllib.parse import urljoin
+
+from app.db.systemconfig_oper import SystemConfigOper
+from app.log import logger
+from app.schemas.agent import (
+    AgentMcpServerConfig,
+    AgentMcpServerTestResult,
+    AgentMcpServerToolInfo,
+)
+from app.schemas.types import SystemConfigKey
+from app.utils.http import AsyncRequestUtils
+
+MCP_PROTOCOL_VERSION = "2025-11-25"
+MCP_CLIENT_NAME = "MoviePilot Agent"
+DEFAULT_MCP_TIMEOUT = 30
+MCP_TOOL_NAME_PATTERN = re.compile(r"[^a-zA-Z0-9_]+")
+
+
+@dataclass(frozen=True)
+class AgentMcpToolSpec:
+    """已发现的外部 MCP 工具定义。"""
+
+    server: AgentMcpServerConfig
+    name: str
+    agent_tool_name: str
+    description: str
+    input_schema: dict[str, Any]
+
+
+def _normalize_identifier(value: str, fallback: str = "mcp") -> str:
+    """把服务器或工具名称转换为 Agent 工具可用的标识片段。"""
+    normalized = MCP_TOOL_NAME_PATTERN.sub("_", str(value or "").strip())
+    normalized = re.sub(r"_+", "_", normalized).strip("_").lower()
+    if not normalized:
+        normalized = fallback
+    if normalized[0].isdigit():
+        normalized = f"{fallback}_{normalized}"
+    return normalized[:64]
+
+
+def _normalize_timeout(value: Any) -> int:
+    """规范化 MCP 连接和调用超时时间。"""
+    try:
+        timeout = int(value or DEFAULT_MCP_TIMEOUT)
+    except (TypeError, ValueError):
+        timeout = DEFAULT_MCP_TIMEOUT
+    return min(max(timeout, 1), 600)
+
+
+def _normalize_string_dict(value: Any) -> dict[str, str]:
+    """规范化请求头和环境变量字典，移除空键。"""
+    if not isinstance(value, dict):
+        return {}
+    normalized: dict[str, str] = {}
+    for key, item in value.items():
+        normalized_key = str(key or "").strip()
+        if not normalized_key:
+            continue
+        normalized[normalized_key] = str(item or "")
+    return normalized
+
+
+def _normalize_input_schema(value: Any) -> dict[str, Any]:
+    """规范化 MCP 工具参数 Schema，保证至少是 object schema。"""
+    if not isinstance(value, dict):
+        return {"type": "object", "properties": {}, "required": []}
+    schema = dict(value)
+    schema.setdefault("type", "object")
+    schema.setdefault("properties", {})
+    schema.setdefault("required", [])
+    return schema
+
+
+def _build_agent_tool_name(server: AgentMcpServerConfig, tool_name: str) -> str:
+    """构造注入 Agent 的外部 MCP 工具名。"""
+    prefix = server.tool_prefix or f"mcp_{server.name or server.id}"
+    normalized_prefix = _normalize_identifier(prefix, fallback="mcp")
+    normalized_tool_name = _normalize_identifier(tool_name, fallback="tool")
+    if normalized_tool_name.startswith(f"{normalized_prefix}_"):
+        return normalized_tool_name
+    return f"{normalized_prefix}_{normalized_tool_name}"[:128]
+
+
+def _jsonrpc_message(method: str, params: Optional[dict[str, Any]] = None, *, request_id: Optional[str] = None) -> dict:
+    """构造 JSON-RPC 2.0 消息。"""
+    payload = {"jsonrpc": "2.0", "method": method}
+    if request_id is not None:
+        payload["id"] = request_id
+    if params is not None:
+        payload["params"] = params
+    return payload
+
+
+def _raise_for_jsonrpc_error(payload: Any) -> None:
+    """检查 JSON-RPC 响应错误并转换为运行时异常。"""
+    if isinstance(payload, dict) and payload.get("error"):
+        error = payload["error"]
+        if isinstance(error, dict):
+            message = error.get("message") or error
+        else:
+            message = error
+        raise RuntimeError(f"MCP JSON-RPC 错误: {message}")
+
+
+def _extract_jsonrpc_result(payload: Any, request_id: str) -> Any:
+    """从 JSON-RPC 响应中提取 result 字段。"""
+    if not isinstance(payload, dict):
+        raise RuntimeError("MCP 响应不是有效 JSON 对象")
+    if payload.get("id") != request_id:
+        raise RuntimeError("MCP 响应 ID 与请求不匹配")
+    _raise_for_jsonrpc_error(payload)
+    return payload.get("result")
+
+
+async def _iter_sse_events(response) -> Any:
+    """按 SSE 事件格式迭代响应流。"""
+    event_name = "message"
+    data_lines: list[str] = []
+    async for raw_line in response.aiter_lines():
+        line = raw_line.rstrip("\r")
+        if not line:
+            if data_lines:
+                yield {"event": event_name, "data": "\n".join(data_lines)}
+            event_name = "message"
+            data_lines = []
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            event_name = value or "message"
+        elif field == "data":
+            data_lines.append(value)
+    if data_lines:
+        yield {"event": event_name, "data": "\n".join(data_lines)}
+
+
+def _parse_sse_text_response(text: str, request_id: str) -> Any:
+    """从非流式 SSE 文本响应中提取匹配请求的 JSON-RPC 结果。"""
+    event_name = "message"
+    data_lines: list[str] = []
+    for raw_line in str(text or "").splitlines():
+        line = raw_line.rstrip("\r")
+        if not line:
+            if data_lines:
+                payload = _load_sse_json_payload(event_name, "\n".join(data_lines))
+                if isinstance(payload, dict) and payload.get("id") == request_id:
+                    return _extract_jsonrpc_result(payload, request_id)
+            event_name = "message"
+            data_lines = []
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            event_name = value or "message"
+        elif field == "data":
+            data_lines.append(value)
+    if data_lines:
+        payload = _load_sse_json_payload(event_name, "\n".join(data_lines))
+        if isinstance(payload, dict) and payload.get("id") == request_id:
+            return _extract_jsonrpc_result(payload, request_id)
+    raise RuntimeError("MCP SSE 响应中未找到匹配请求")
+
+
+def _load_sse_json_payload(event_name: str, data: str) -> Optional[dict]:
+    """解析 SSE data 中的 JSON-RPC 消息。"""
+    if event_name not in {"message", "messages"}:
+        return None
+    try:
+        payload = json.loads(data)
+    except (TypeError, ValueError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+class _StdioMcpSession:
+    """stdio MCP 会话，按一次操作生命周期启动外部进程。"""
+
+    def __init__(self, server: AgentMcpServerConfig) -> None:
+        self.server = server
+        self.process: Optional[asyncio.subprocess.Process] = None
+        self.stderr_task: Optional[asyncio.Task] = None
+
+    async def __aenter__(self) -> "_StdioMcpSession":
+        """启动 stdio MCP 子进程。"""
+        if not self.server.command:
+            raise RuntimeError("stdio MCP 服务器缺少启动命令")
+        env = os.environ.copy()
+        env.update(self.server.env or {})
+        self.process = await asyncio.create_subprocess_exec(
+            self.server.command,
+            *(self.server.args or []),
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+        self.stderr_task = asyncio.create_task(self._drain_stderr())
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        """结束 stdio MCP 子进程。"""
+        if self.stderr_task:
+            self.stderr_task.cancel()
+        if not self.process:
+            return
+        if self.process.returncode is None:
+            self.process.terminate()
+            try:
+                await asyncio.wait_for(self.process.wait(), timeout=2)
+            except asyncio.TimeoutError:
+                self.process.kill()
+                await self.process.wait()
+
+    async def _drain_stderr(self) -> None:
+        """持续读取子进程 stderr，避免缓冲区阻塞。"""
+        if not self.process or not self.process.stderr:
+            return
+        try:
+            while True:
+                line = await self.process.stderr.readline()
+                if not line:
+                    break
+                logger.debug(f"MCP stdio[{self.server.name}] stderr: {line.decode(errors='replace').strip()}")
+        except asyncio.CancelledError:
+            return
+
+    async def notify(self, method: str, params: Optional[dict[str, Any]] = None) -> None:
+        """发送不需要响应的 JSON-RPC 通知。"""
+        await self._write_json(_jsonrpc_message(method, params))
+
+    async def request(self, method: str, params: Optional[dict[str, Any]] = None) -> Any:
+        """发送 JSON-RPC 请求并等待响应。"""
+        request_id = uuid.uuid4().hex
+        await self._write_json(_jsonrpc_message(method, params, request_id=request_id))
+        while True:
+            payload = await self._read_json()
+            if payload.get("id") == request_id:
+                return _extract_jsonrpc_result(payload, request_id)
+
+    async def _write_json(self, payload: dict) -> None:
+        """写入一行 JSON-RPC 消息。"""
+        if not self.process or not self.process.stdin:
+            raise RuntimeError("stdio MCP 进程未启动")
+        data = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+        self.process.stdin.write(data.encode("utf-8"))
+        await self.process.stdin.drain()
+
+    async def _read_json(self) -> dict:
+        """从 stdout 读取一行 JSON-RPC 消息。"""
+        if not self.process or not self.process.stdout:
+            raise RuntimeError("stdio MCP 进程未启动")
+        timeout = _normalize_timeout(self.server.timeout)
+        while True:
+            line = await asyncio.wait_for(self.process.stdout.readline(), timeout=timeout)
+            if not line:
+                raise RuntimeError("stdio MCP 进程已退出")
+            try:
+                payload = json.loads(line.decode("utf-8"))
+            except ValueError:
+                logger.debug(f"忽略非 JSON MCP stdout 行: {line!r}")
+                continue
+            if isinstance(payload, dict):
+                return payload
+
+
+class _HttpMcpSession:
+    """Streamable HTTP MCP 会话。"""
+
+    def __init__(self, server: AgentMcpServerConfig) -> None:
+        self.server = server
+        self.session_id: Optional[str] = None
+
+    async def __aenter__(self) -> "_HttpMcpSession":
+        """进入 HTTP MCP 会话。"""
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        """退出 HTTP MCP 会话。"""
+        return None
+
+    async def notify(self, method: str, params: Optional[dict[str, Any]] = None) -> None:
+        """发送不需要响应的 JSON-RPC 通知。"""
+        await self._post(_jsonrpc_message(method, params), expect_response=False)
+
+    async def request(self, method: str, params: Optional[dict[str, Any]] = None) -> Any:
+        """发送 JSON-RPC 请求并等待响应。"""
+        request_id = uuid.uuid4().hex
+        return await self._post(
+            _jsonrpc_message(method, params, request_id=request_id),
+            expect_response=True,
+            request_id=request_id,
+        )
+
+    async def _post(
+        self,
+        payload: dict,
+        *,
+        expect_response: bool,
+        request_id: Optional[str] = None,
+    ) -> Any:
+        """向 Streamable HTTP MCP 服务发送一条 JSON-RPC 消息。"""
+        if not self.server.url:
+            raise RuntimeError("HTTP MCP 服务器缺少 URL")
+        headers = {
+            "Accept": "application/json, text/event-stream",
+            "Content-Type": "application/json",
+            **(self.server.headers or {}),
+        }
+        if self.session_id:
+            headers["Mcp-Session-Id"] = self.session_id
+        response = await AsyncRequestUtils(
+            headers=headers,
+            timeout=_normalize_timeout(self.server.timeout),
+            content_type="application/json",
+            accept_type="application/json, text/event-stream",
+            http2=False,
+        ).post_res(self.server.url, json=payload, raise_exception=True)
+        try:
+            if not response:
+                raise RuntimeError("HTTP MCP 请求无响应")
+            response.raise_for_status()
+            session_id = response.headers.get("Mcp-Session-Id")
+            if session_id:
+                self.session_id = session_id
+            if not expect_response:
+                return None
+            content_type = response.headers.get("content-type", "").lower()
+            if "text/event-stream" in content_type:
+                return _parse_sse_text_response(response.text, request_id or "")
+            data = response.json()
+            return _extract_jsonrpc_result(data, request_id or "")
+        finally:
+            if response is not None:
+                await response.aclose()
+
+
+class _SseMcpSession:
+    """旧版 HTTP+SSE MCP 会话。"""
+
+    def __init__(self, server: AgentMcpServerConfig) -> None:
+        self.server = server
+        self.response = None
+        self.endpoint: Optional[str] = None
+        self._stream_manager = None
+        self._event_iterator = None
+
+    async def __aenter__(self) -> "_SseMcpSession":
+        """打开 SSE 流并读取服务端回传的 POST endpoint。"""
+        if not self.server.url:
+            raise RuntimeError("SSE MCP 服务器缺少 URL")
+        self._stream_manager = AsyncRequestUtils(
+            headers={"Accept": "text/event-stream", **(self.server.headers or {})},
+            timeout=_normalize_timeout(self.server.timeout),
+            accept_type="text/event-stream",
+            http2=False,
+        ).get_stream(self.server.url, raise_exception=True)
+        self.response = await self._stream_manager.__aenter__()
+        if not self.response:
+            raise RuntimeError("SSE MCP 连接无响应")
+        self.response.raise_for_status()
+        self._event_iterator = _iter_sse_events(self.response).__aiter__()
+        self.endpoint = await self._read_endpoint()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        """关闭 SSE 流。"""
+        if self._stream_manager:
+            await self._stream_manager.__aexit__(exc_type, exc, tb)
+
+    async def notify(self, method: str, params: Optional[dict[str, Any]] = None) -> None:
+        """发送不需要响应的 JSON-RPC 通知。"""
+        await self._post(_jsonrpc_message(method, params))
+
+    async def request(self, method: str, params: Optional[dict[str, Any]] = None) -> Any:
+        """发送 JSON-RPC 请求并等待 SSE 流上的响应。"""
+        request_id = uuid.uuid4().hex
+        await self._post(_jsonrpc_message(method, params, request_id=request_id))
+        timeout = _normalize_timeout(self.server.timeout)
+        while True:
+            event = await asyncio.wait_for(self._event_iterator.__anext__(), timeout=timeout)
+            payload = _load_sse_json_payload(event.get("event", ""), event.get("data", ""))
+            if isinstance(payload, dict) and payload.get("id") == request_id:
+                return _extract_jsonrpc_result(payload, request_id)
+
+    async def _read_endpoint(self) -> str:
+        """读取 SSE endpoint 事件中的 POST 地址。"""
+        timeout = _normalize_timeout(self.server.timeout)
+        while True:
+            event = await asyncio.wait_for(self._event_iterator.__anext__(), timeout=timeout)
+            if event.get("event") != "endpoint":
+                continue
+            endpoint = str(event.get("data") or "").strip()
+            if not endpoint:
+                continue
+            return urljoin(self.server.url, endpoint)
+
+    async def _post(self, payload: dict) -> None:
+        """向 SSE 握手返回的 endpoint 发送 JSON-RPC 消息。"""
+        if not self.endpoint:
+            raise RuntimeError("SSE MCP endpoint 未初始化")
+        response = await AsyncRequestUtils(
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                **(self.server.headers or {}),
+            },
+            timeout=_normalize_timeout(self.server.timeout),
+            content_type="application/json",
+            accept_type="application/json",
+            http2=False,
+        ).post_res(self.endpoint, json=payload, raise_exception=True)
+        try:
+            if not response:
+                raise RuntimeError("SSE MCP POST 请求无响应")
+            response.raise_for_status()
+        finally:
+            if response is not None:
+                await response.aclose()
+
+
+async def _open_mcp_session(server: AgentMcpServerConfig):
+    """根据配置创建对应的 MCP 传输会话。"""
+    transport = "http" if server.transport == "streamable_http" else server.transport
+    if transport == "stdio":
+        return _StdioMcpSession(server)
+    if transport == "sse":
+        return _SseMcpSession(server)
+    if transport == "http":
+        return _HttpMcpSession(server)
+    raise RuntimeError(f"不支持的 MCP 传输协议: {server.transport}")
+
+
+class AgentMcpManager:
+    """管理 Agent 外部 MCP 服务器配置、工具发现和工具调用。"""
+
+    def get_servers(self) -> list[AgentMcpServerConfig]:
+        """读取已保存的外部 MCP 服务器配置。"""
+        raw_servers = SystemConfigOper().get(SystemConfigKey.AIAgentMcpServers) or []
+        if not isinstance(raw_servers, list):
+            return []
+        servers: list[AgentMcpServerConfig] = []
+        for raw_server in raw_servers:
+            try:
+                servers.append(self.normalize_server(raw_server))
+            except Exception as err:
+                logger.warning(f"忽略无效的 Agent MCP 配置: {err}")
+        return servers
+
+    async def save_servers(self, servers: list[AgentMcpServerConfig]) -> bool:
+        """保存外部 MCP 服务器配置。"""
+        normalized_servers = [self.normalize_server(server).model_dump() for server in servers]
+        return await SystemConfigOper().async_set(
+            SystemConfigKey.AIAgentMcpServers,
+            normalized_servers or None,
+        )
+
+    def normalize_server(self, value: Any) -> AgentMcpServerConfig:
+        """规范化单个 MCP 服务器配置。"""
+        if isinstance(value, AgentMcpServerConfig):
+            raw_server = value.model_dump()
+        elif isinstance(value, dict):
+            raw_server = dict(value)
+        else:
+            raise ValueError("MCP 服务器配置必须是对象")
+
+        raw_server["id"] = str(raw_server.get("id") or uuid.uuid4().hex[:12]).strip()
+        raw_server["name"] = str(raw_server.get("name") or raw_server["id"]).strip()
+        raw_server["transport"] = str(raw_server.get("transport") or "stdio").strip()
+        raw_server["description"] = str(raw_server.get("description") or "").strip() or None
+        raw_server["command"] = str(raw_server.get("command") or "").strip() or None
+        raw_server["args"] = [str(item) for item in raw_server.get("args") or []]
+        raw_server["env"] = _normalize_string_dict(raw_server.get("env"))
+        raw_server["url"] = str(raw_server.get("url") or "").strip() or None
+        raw_server["headers"] = _normalize_string_dict(raw_server.get("headers"))
+        raw_server["timeout"] = _normalize_timeout(raw_server.get("timeout"))
+        raw_server["tool_prefix"] = str(raw_server.get("tool_prefix") or "").strip() or None
+        raw_server["require_admin"] = bool(raw_server.get("require_admin", True))
+        return AgentMcpServerConfig.model_validate(raw_server)
+
+    def config_signature(self) -> str:
+        """生成外部 MCP 配置签名，用于 Agent 图缓存失效。"""
+        payload = [server.model_dump() for server in self.get_servers()]
+        raw_text = json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str)
+        return hashlib.sha256(raw_text.encode("utf-8")).hexdigest()
+
+    async def initialize_session(self, session) -> None:
+        """完成 MCP initialize 和 initialized 通知流程。"""
+        await session.request(
+            "initialize",
+            {
+                "protocolVersion": MCP_PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {
+                    "name": MCP_CLIENT_NAME,
+                    "version": "1.0.0",
+                },
+            },
+        )
+        await session.notify("notifications/initialized")
+
+    async def list_server_tools(self, server: AgentMcpServerConfig) -> list[AgentMcpToolSpec]:
+        """连接单个 MCP 服务器并读取工具列表。"""
+        normalized_server = self.normalize_server(server)
+        session_manager = await _open_mcp_session(normalized_server)
+        async with session_manager as session:
+            await self.initialize_session(session)
+            result = await session.request("tools/list")
+        tools_payload = result.get("tools", []) if isinstance(result, dict) else []
+        tool_specs: list[AgentMcpToolSpec] = []
+        for item in tools_payload:
+            if not isinstance(item, dict) or not item.get("name"):
+                continue
+            tool_name = str(item["name"])
+            tool_specs.append(
+                AgentMcpToolSpec(
+                    server=normalized_server,
+                    name=tool_name,
+                    agent_tool_name=_build_agent_tool_name(normalized_server, tool_name),
+                    description=str(item.get("description") or ""),
+                    input_schema=_normalize_input_schema(item.get("inputSchema")),
+                )
+            )
+        return tool_specs
+
+    async def list_enabled_tool_specs(self) -> list[AgentMcpToolSpec]:
+        """读取所有启用 MCP 服务器暴露的工具定义。"""
+        tool_specs: list[AgentMcpToolSpec] = []
+        seen_names: set[str] = set()
+        for server in self.get_servers():
+            if not server.enabled:
+                continue
+            try:
+                for spec in await self.list_server_tools(server):
+                    if spec.agent_tool_name in seen_names:
+                        logger.warning(f"跳过重复的 MCP Agent 工具名: {spec.agent_tool_name}")
+                        continue
+                    tool_specs.append(spec)
+                    seen_names.add(spec.agent_tool_name)
+            except Exception as err:
+                logger.warning(f"读取 MCP 服务器 {server.name} 工具失败: {err}")
+        return tool_specs
+
+    async def call_server_tool(
+        self,
+        server: AgentMcpServerConfig,
+        tool_name: str,
+        arguments: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """调用单个 MCP 服务器上的指定工具。"""
+        normalized_server = self.normalize_server(server)
+        session_manager = await _open_mcp_session(normalized_server)
+        async with session_manager as session:
+            await self.initialize_session(session)
+            return await session.request(
+                "tools/call",
+                {
+                    "name": tool_name,
+                    "arguments": arguments or {},
+                },
+            )
+
+    async def test_server(self, server: AgentMcpServerConfig) -> AgentMcpServerTestResult:
+        """测试 MCP 服务器连接并返回工具列表。"""
+        tool_specs = await self.list_server_tools(server)
+        tools = [
+            AgentMcpServerToolInfo(
+                name=spec.name,
+                agent_tool_name=spec.agent_tool_name,
+                description=spec.description,
+                input_schema=spec.input_schema,
+            )
+            for spec in tool_specs
+        ]
+        return AgentMcpServerTestResult(
+            success=True,
+            message=f"连接成功，发现 {len(tools)} 个工具",
+            tools=tools,
+            tool_count=len(tools),
+        )
+
+
+agent_mcp_manager = AgentMcpManager()

app/agent/memory/__init__.py

@@ -4,9 +4,10 @@ import asyncio
 from datetime import datetime
 from typing import Dict, List, Optional
 
-from langchain_core.messages import BaseMessage
+from langchain_core.messages import BaseMessage, messages_from_dict, messages_to_dict
 
 from app.core.config import settings
+from app.db.agentchat_oper import AgentChatOper
 from app.log import logger
 from app.schemas.agent import ConversationMemory
 
@@ -70,24 +71,43 @@ class MemoryManager:
             self, session_id: str, user_id: str
     ) -> List[BaseMessage]:
         """
-        为Agent获取最近的消息（仅内存缓存）
+        为Agent获取最近的消息。
 
-        如果消息Token数量超过模型最大上下文长度的阀值，会自动进行摘要裁剪
+        优先使用内存缓存，缓存不存在时从数据库恢复上一轮持久化的原始 messages。
         """
         memory = self.get_memory(session_id, user_id)
-        if not memory:
+        if memory:
+            return memory.messages
+
+        try:
+            chat = AgentChatOper().get(session_id=session_id, user_id=user_id)
+            if not chat:
+                chat = AgentChatOper().get(session_id=session_id)
+        except Exception as e:
+            logger.debug(f"读取持久化Agent会话失败: {e}")
+            return []
+        if not chat or not chat.agent_messages:
             return []
 
-        # 获取所有消息
+        try:
+            messages = messages_from_dict(chat.agent_messages)
+        except Exception as e:
+            logger.debug(f"恢复持久化Agent消息失败: {e}")
+            return []
+
+        memory = ConversationMemory(
+            session_id=session_id,
+            user_id=user_id,
+            messages=messages,
+        )
+        self.save_memory(memory)
         return memory.messages
 
     def save_agent_messages(
             self, session_id: str, user_id: str, messages: List[BaseMessage]
     ):
         """
-        保存Agent消息（仅内存缓存）
-
-        注意：Redis中的记忆通过TTL机制自动过期，这里只更新内存缓存，Redis会在下次访问时自动过期
+        保存Agent消息到内存缓存与持久化会话表。
         """
         memory = self.get_memory(session_id, user_id)
         if not memory:
@@ -98,6 +118,14 @@ class MemoryManager:
 
         # 更新内存缓存
         self.save_memory(memory)
+        try:
+            AgentChatOper().save_agent_messages(
+                session_id=session_id,
+                user_id=user_id,
+                messages=messages_to_dict(messages),
+            )
+        except Exception as e:
+            logger.debug(f"持久化Agent消息失败: {e}")
 
     def save_memory(self, memory: ConversationMemory):
         """

app/agent/middleware/activity_log.py

@@ -3,14 +3,19 @@
 
 按日期存储在 CONFIG_PATH/agent/activity/YYYY-MM-DD.md 中，
 每次 Agent 执行完毕后自动调用 LLM 对本轮对话生成简洁的活动摘要，
-并在每次 Agent 启动时加载近几天的活动日志注入系统提示词。
+系统提示词只注入稳定的检索规则，完整日志由工具按需查询。
 """
 
+import asyncio
+import json
+import os
 import re
 from collections.abc import Awaitable, Callable
 from datetime import datetime, timedelta
-from typing import Annotated, Any, NotRequired, TypedDict
+from pathlib import Path
+from typing import Annotated, Any, NotRequired, Optional, TypedDict
 
+import anyio
 from anyio import Path as AsyncPath
 from langchain.agents.middleware.types import (
     AgentMiddleware,
@@ -20,39 +25,302 @@ from langchain.agents.middleware.types import (
     ModelResponse,
     PrivateStateAttr,  # noqa
     ResponseT,
+    ToolCallRequest,
 )
 from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+from langchain_core.tools import StructuredTool
 from langgraph.runtime import Runtime
+from pydantic import BaseModel, Field
 
 from app.agent.middleware.utils import append_to_system_message
+from app.agent.tools.tags import ToolTag
 from app.log import logger
 
 # 活动日志保留天数
 DEFAULT_RETENTION_DAYS = 7
 
-# 注入系统提示词时加载的天数
+# 注入系统提示词时索引的天数
 PROMPT_LOAD_DAYS = 3
 
+# 工具默认查询的天数
+DEFAULT_QUERY_DAYS = 7
+
+# 工具单次返回的最大条数
+DEFAULT_QUERY_LIMIT = 20
+MAX_QUERY_LIMIT = 50
+
 # 每日日志文件最大大小 (256KB)
 MAX_LOG_FILE_SIZE = 256 * 1024
 
 # 提取本轮对话上下文的最大字符数（避免过长的对话消耗太多 token）
 MAX_CONTEXT_FOR_SUMMARY = 4000
 
+SUMMARY_SKIP_MARKER = "SKIP"
+QUERY_ACTIVITY_LOG_TOOL_NAME = "query_activity_log"
+QUERY_ACTIVITY_LOG_TOOL_DESCRIPTION = (
+    "Query recent MoviePilot Agent activity logs on demand. Use this when the user asks what was done before, "
+    "asks to continue a previous task, or explicitly references recent agent activity. Supports keyword, date, "
+    "recent-day window, limit, and optional regex filters. If a keyword search returns no results, retry with "
+    "a shorter keyword, a larger days window, or no keyword to inspect recent entries."
+)
+
 # LLM 总结的提示词
-SUMMARY_PROMPT = """请根据以下 AI 助手与用户的对话记录，生成一条简洁的活动摘要（中文，一句话，不超过80字）。
-摘要应包含：用户的需求是什么、助手做了什么、结果如何。
-只输出摘要内容，不要加任何前缀、标点序号或解释。
+SUMMARY_PROMPT = """请判断以下 AI 助手与用户的对话是否值得写入 MoviePilot 活动日志。
+
+如果本轮只是问候、寒暄、感谢、确认、闲聊、没有实际任务、没有工具动作、任务没有推进、纯粹的格式纠正或无意义空转，请只输出：SKIP
+
+如果值得记录，请输出一条中文单行活动摘要，要求：
+- 40 到 160 个汉字左右，信息密度高，不要写成泛泛一句话。
+- 只输出摘要正文，不要标题、编号、Markdown、JSON 或解释。
+- 尽量包含：用户目标、关键对象（影片/剧集/站点/路径/任务/设置）、助手采取的关键动作或工具、结果状态、失败原因或下一步。
+- 如果有明确 ID、路径、站点名、任务状态、成功/失败数量，请保留关键值。
+- 不要记录 API Key、Cookie、Token、密码等敏感信息；如出现请写成“敏感信息已省略”。
+
+推荐格式示例：
+用户要求整理 `/downloads/Show`，助手识别为《示例剧》TMDB 12345，并提交 transfer_file 整理，结果成功。
+用户排查下载失败，助手查询 qBittorrent 任务和站点状态，发现 tracker 超时，建议更换站点或重试。
 
 对话记录：
 {conversation}"""
 
+ACTIVITY_ENTRY_PATTERN = re.compile(r"^-\s+\*\*(?P<time>\d{2}:\d{2})\*\*\s+(?P<summary>.+)$")
+
+
+class QueryActivityLogInput(BaseModel):
+    """查询活动日志工具的输入参数模型。"""
+
+    keyword: Optional[str] = Field(
+        None,
+        description=(
+            "Optional plain-text keyword to filter activity summaries. Use short title, path, site, task, "
+            "or status fragments; omit it to inspect latest entries."
+        ),
+    )
+    use_regex: Optional[bool] = Field(
+        False,
+        description=(
+            "Whether to treat keyword as a regular expression. Defaults to false; enable only for "
+            "alternative or pattern matching."
+        ),
+    )
+    date: Optional[str] = Field(
+        None,
+        description="Optional exact date in YYYY-MM-DD format. If omitted, recent days are searched.",
+    )
+    days: Optional[int] = Field(
+        DEFAULT_QUERY_DAYS,
+        description="Number of recent days to search when date is not specified.",
+    )
+    limit: Optional[int] = Field(
+        DEFAULT_QUERY_LIMIT,
+        description="Maximum number of activity entries to return.",
+    )
+
+
+def _coerce_query_limit(limit: Optional[int]) -> int:
+    """规范化活动日志查询条数。"""
+    if limit is None:
+        return DEFAULT_QUERY_LIMIT
+    try:
+        value = int(limit)
+    except (TypeError, ValueError):
+        return DEFAULT_QUERY_LIMIT
+    return min(max(value, 1), MAX_QUERY_LIMIT)
+
+
+def _build_log_path(activity_dir: str, date_str: str) -> Path:
+    """构建指定日期的活动日志路径。"""
+    return Path(activity_dir) / f"{date_str}.md"
+
+
+def _iter_recent_dates(days: int) -> list[str]:
+    """返回从今天开始向前的日期字符串列表。"""
+    normalized_days = max(1, int(days or 1))
+    today = datetime.now().date()
+    return [
+        (today - timedelta(days=index)).strftime("%Y-%m-%d")
+        for index in range(normalized_days)
+    ]
+
+
+def _parse_activity_entries(date_str: str, content: str) -> list[dict[str, str]]:
+    """从单日活动日志 Markdown 中解析活动条目。"""
+    entries: list[dict[str, str]] = []
+    for line in content.splitlines():
+        match = ACTIVITY_ENTRY_PATTERN.match(line.strip())
+        if not match:
+            continue
+        entries.append(
+            {
+                "date": date_str,
+                "time": match.group("time"),
+                "summary": match.group("summary").strip(),
+            }
+        )
+    return entries
+
+
+def _activity_summary_matches_keyword(
+    summary: str,
+    keyword: str,
+    regex_pattern: Optional[re.Pattern[str]],
+) -> bool:
+    """判断活动摘要是否命中普通关键词或正则表达式。"""
+    if regex_pattern:
+        return bool(regex_pattern.search(summary))
+    return keyword.lower() in summary.lower()
+
+
+def load_activity_log_index(activity_dir: str, days: int = PROMPT_LOAD_DAYS) -> dict[str, str]:
+    """加载近期活动日志索引，不返回完整日志正文。"""
+    index: dict[str, str] = {}
+    for date_str in _iter_recent_dates(days):
+        log_path = _build_log_path(activity_dir, date_str)
+        if not log_path.is_file():
+            continue
+        try:
+            content = log_path.read_text(encoding="utf-8", errors="replace")
+        except Exception as e:
+            logger.warning(f"读取活动日志索引失败 {log_path}: {e}")
+            continue
+        entry_count = len(_parse_activity_entries(date_str, content))
+        if entry_count:
+            index[date_str] = f"{entry_count} 条活动记录"
+    return index
+
+
+def query_activity_logs(
+    activity_dir: str,
+    *,
+    keyword: Optional[str] = None,
+    use_regex: bool = False,
+    date: Optional[str] = None,
+    days: int = DEFAULT_QUERY_DAYS,
+    limit: Optional[int] = DEFAULT_QUERY_LIMIT,
+) -> dict[str, Any]:
+    """
+    查询活动日志条目。
+
+    :param activity_dir: 活动日志目录
+    :param keyword: 可选关键词，按摘要文本过滤
+    :param use_regex: 是否将关键词按正则表达式匹配
+    :param date: 可选日期，格式为 ``YYYY-MM-DD``
+    :param days: 未指定日期时向前查询的天数
+    :param limit: 返回条数上限
+    :return: 查询结果载荷
+    """
+    normalized_limit = _coerce_query_limit(limit)
+    normalized_keyword = str(keyword or "").strip()
+    normalized_use_regex = bool(use_regex)
+    regex_pattern: Optional[re.Pattern[str]] = None
+    if normalized_keyword and normalized_use_regex:
+        try:
+            regex_pattern = re.compile(normalized_keyword, re.IGNORECASE)
+        except re.error as err:
+            return {
+                "success": False,
+                "message": f"无效的活动日志正则表达式: {err}",
+                "activity_dir": activity_dir,
+                "keyword": normalized_keyword,
+                "use_regex": normalized_use_regex,
+                "date": date,
+                "days": days if not date else None,
+                "searched_dates": [],
+                "total_count": 0,
+                "returned_count": 0,
+                "truncated": False,
+                "entries": [],
+            }
+    date_candidates = [date] if date else _iter_recent_dates(days)
+    entries: list[dict[str, str]] = []
+    searched_dates: list[str] = []
+
+    for date_str in date_candidates:
+        if not date_str:
+            continue
+        searched_dates.append(date_str)
+        log_path = _build_log_path(activity_dir, date_str)
+        if not log_path.is_file():
+            continue
+        try:
+            content = log_path.read_text(encoding="utf-8", errors="replace")
+        except Exception as e:
+            logger.warning(f"读取活动日志失败 {log_path}: {e}")
+            continue
+        for entry in _parse_activity_entries(date_str, content):
+            if normalized_keyword and not _activity_summary_matches_keyword(
+                entry["summary"], normalized_keyword, regex_pattern
+            ):
+                continue
+            entries.append(entry)
+
+    entries.sort(key=lambda item: (item["date"], item["time"]), reverse=True)
+    total_count = len(entries)
+    return {
+        "success": True,
+        "activity_dir": activity_dir,
+        "keyword": normalized_keyword or None,
+        "use_regex": normalized_use_regex,
+        "date": date,
+        "days": days if not date else None,
+        "searched_dates": searched_dates,
+        "total_count": total_count,
+        "returned_count": min(total_count, normalized_limit),
+        "truncated": total_count > normalized_limit,
+        "entries": entries[:normalized_limit],
+    }
+
+
+class _ActivityLogToolProvider:
+    """活动日志工具的查询实现。"""
+
+    def __init__(self, *, activity_dir: str) -> None:
+        """初始化活动日志查询目录。"""
+        self._activity_dir = activity_dir
+
+    async def query_activity_log(
+        self,
+        keyword: Optional[str] = None,
+        use_regex: Optional[bool] = False,
+        date: Optional[str] = None,
+        days: Optional[int] = DEFAULT_QUERY_DAYS,
+        limit: Optional[int] = DEFAULT_QUERY_LIMIT,
+    ) -> str:
+        """查询活动日志并返回 JSON 字符串。"""
+        logger.info(
+            "查询活动日志: keyword=%s, use_regex=%s, date=%s, days=%s, limit=%s",
+            keyword,
+            use_regex,
+            date,
+            days,
+            limit,
+        )
+        try:
+            payload = query_activity_logs(
+                self._activity_dir,
+                keyword=keyword,
+                use_regex=bool(use_regex),
+                date=date,
+                days=days or DEFAULT_QUERY_DAYS,
+                limit=limit,
+            )
+            return json.dumps(payload, ensure_ascii=False, indent=2)
+        except Exception as err:
+            logger.error(f"查询活动日志失败: {err}", exc_info=True)
+            return json.dumps(
+                {
+                    "success": False,
+                    "message": f"查询活动日志时发生错误: {str(err)}",
+                },
+                ensure_ascii=False,
+            )
+
 
 class ActivityLogState(AgentState):
     """ActivityLogMiddleware 的状态模型。"""
 
     activity_log_contents: NotRequired[Annotated[dict[str, str], PrivateStateAttr]]
-    """将日期字符串映射到日志内容的字典。标记为私有，不包含在最终代理状态中。"""
+    """将日期字符串映射到日志索引摘要的字典。标记为私有，不包含在最终代理状态中。"""
 
 
 class ActivityLogStateUpdate(TypedDict):
@@ -61,7 +329,7 @@ class ActivityLogStateUpdate(TypedDict):
     activity_log_contents: dict[str, str]
 
 
-def _extract_last_round(messages: list) -> list | None:
+def _extract_last_round(messages: list) -> Optional[list]:
     """从完整消息列表中提取最后一轮交互。
 
     从最后一条 HumanMessage 到消息末尾即为本轮交互。
@@ -148,7 +416,23 @@ def _format_conversation_for_summary(round_messages: list) -> str:
     return "\n".join(lines)
 
 
-async def _summarize_with_llm(conversation_text: str) -> str | None:
+def _should_skip_activity_summary(round_messages: list) -> bool:
+    """判断本轮交互是否无需生成活动日志。"""
+    if not round_messages:
+        return True
+
+    has_tool_activity = any(
+        isinstance(msg, ToolMessage)
+        or (isinstance(msg, AIMessage) and bool(getattr(msg, "tool_calls", None)))
+        for msg in round_messages
+    )
+    if has_tool_activity:
+        return False
+
+    return True
+
+
+async def _summarize_with_llm(conversation_text: str) -> Optional[str]:
     """调用 LLM 对对话文本生成活动摘要。
 
     参数：
@@ -163,53 +447,38 @@ async def _summarize_with_llm(conversation_text: str) -> str | None:
         llm = await LLMHelper.get_llm(streaming=False)
         prompt = SUMMARY_PROMPT.format(conversation=conversation_text)
         response = await llm.ainvoke(prompt)
-        summary = response.content.strip()
+        summary = LLMHelper.extract_text_content(response.content).strip()
         # 清理模型可能输出的前缀（如 "摘要：" "总结："）
         summary = re.sub(r"^(摘要|总结|活动记录)[：:]\s*", "", summary)
+        if summary.strip().upper() == SUMMARY_SKIP_MARKER:
+            return None
         return summary if summary else None
     except Exception as e:
-        logger.debug("LLM summarization failed: %s", e)
+        logger.debug(f"LLM 活动摘要生成失败: {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 contents and indexes are not included in the default context.
+    Use `query_activity_log` only when the user references previous work, asks to continue a prior task, or recent activity is clearly relevant.
+    Activity logs are read-only and retained for {retention_days} days; use MEMORY.md for durable preferences.
 </activity_log_guidelines>
+</activity_log>
 """
 
 
 class ActivityLogMiddleware(AgentMiddleware[ActivityLogState, ContextT, ResponseT]):  # noqa
-    """自动记录和加载 Agent 活动日志的中间件。
+    """自动记录 Agent 活动日志并注入稳定检索规则的中间件。
 
-    - abefore_agent: 加载近几天的活动日志
-    - awrap_model_call: 将活动日志注入系统提示词
+    - abefore_agent: 加载近几天的活动日志索引
+    - awrap_model_call: 将固定的活动日志检索规则注入系统提示词
     - aafter_agent: 从本次对话中提取摘要并追加到当日日志文件
 
     参数：
         activity_dir: 活动日志存储目录路径。
         retention_days: 日志保留天数（默认 7 天）。
-        prompt_load_days: 注入系统提示词时加载的天数（默认 3 天）。
+        prompt_load_days: 注入系统提示词时索引的天数（默认 3 天）。
     """
 
     state_schema = ActivityLogState
@@ -220,62 +489,41 @@ class ActivityLogMiddleware(AgentMiddleware[ActivityLogState, ContextT, Response
         activity_dir: str,
         retention_days: int = DEFAULT_RETENTION_DAYS,
         prompt_load_days: int = PROMPT_LOAD_DAYS,
+        stream_handler: Optional[Any] = None,
     ) -> None:
+        """初始化活动日志中间件。"""
         self.activity_dir = activity_dir
         self.retention_days = retention_days
         self.prompt_load_days = prompt_load_days
+        self.stream_handler = stream_handler
+        self._background_tasks: set[asyncio.Task[None]] = set()
+        self._tool_provider = _ActivityLogToolProvider(activity_dir=activity_dir)
+        self.tools = [
+            StructuredTool.from_function(
+                coroutine=self._tool_provider.query_activity_log,
+                name=QUERY_ACTIVITY_LOG_TOOL_NAME,
+                description=QUERY_ACTIVITY_LOG_TOOL_DESCRIPTION,
+                args_schema=QueryActivityLogInput,
+                tags=[ToolTag.Read, ToolTag.System],
+            )
+        ]
 
     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)
+    def _format_activity_log(self, _contents: dict[str, str]) -> str:
+        """生成不受活动日志内容变化影响的系统提示词。"""
         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
+        """加载近几天的活动日志索引。"""
+        return load_activity_log_index(
+            activity_dir=self.activity_dir,
+            days=self.prompt_load_days,
+        )
 
     async def _append_activity(self, summary: str) -> None:
         """将一条活动记录追加到当日日志文件。"""
@@ -303,14 +551,29 @@ class ActivityLogMiddleware(AgentMiddleware[ActivityLogState, ContextT, Response
         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")
+                async with await anyio.open_file(
+                    log_path,
+                    mode="a",
+                    encoding="utf-8",
+                ) as stream:
+                    await stream.write(entry)
             else:
                 header = f"# {today_str} 活动日志\n\n"
-                await log_path.write_text(header + entry, encoding="utf-8")
-            logger.debug("Activity logged: %s", summary[:80])
+                try:
+                    fd = os.open(log_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
+                except FileExistsError:
+                    async with await anyio.open_file(
+                        log_path,
+                        mode="a",
+                        encoding="utf-8",
+                    ) as stream:
+                        await stream.write(entry)
+                else:
+                    with os.fdopen(fd, "w", encoding="utf-8") as stream:
+                        stream.write(header + entry)
+            logger.debug(f"Activity logged: {summary[:80]}")
         except Exception as e:
-            logger.warning("Failed to append activity log: %s", e)
+            logger.warning(f"Failed to append activity log: {e}")
 
     async def _cleanup_old_logs(self) -> None:
         """清理超过保留天数的旧日志文件。"""
@@ -332,20 +595,54 @@ class ActivityLogMiddleware(AgentMiddleware[ActivityLogState, ContextT, Response
                     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)
+                        logger.debug(f"Cleaned up old activity log: {path.name}")
                 except ValueError:
                     continue
         except Exception as e:
-            logger.warning("Failed to cleanup old activity logs: %s", e)
+            logger.warning(f"Failed to cleanup old activity logs: {e}")
+
+    def _schedule_activity_recording(self, messages: list) -> None:
+        """提交后台活动记录任务，不阻塞当前 Agent 会话结束。"""
+        task = asyncio.create_task(self._record_activity(messages))
+        self._background_tasks.add(task)
+        task.add_done_callback(self._on_activity_recording_done)
+
+    def _on_activity_recording_done(self, task: asyncio.Task[None]) -> None:
+        """清理已完成的后台任务并记录未捕获异常。"""
+        self._background_tasks.discard(task)
+        try:
+            task.result()
+        except asyncio.CancelledError:
+            logger.debug("活动日志后台记录任务已取消")
+        except Exception as err:
+            logger.warning(f"活动日志后台记录任务失败: {err}")
+
+    async def _record_activity(self, messages: list) -> None:
+        """在后台生成本轮活动摘要并写入活动日志。"""
+        try:
+            # 提取本轮交互
+            round_messages = _extract_last_round(messages)
+            if not round_messages:
+                return
+            if _should_skip_activity_summary(round_messages):
+                return
+
+            # 格式化对话文本
+            conversation_text = _format_conversation_for_summary(round_messages)
+            if not conversation_text:
+                return
+
+            # 调用 LLM 生成摘要
+            summary = await _summarize_with_llm(conversation_text)
+            if summary:
+                await self._append_activity(summary)
+        except Exception as e:
+            logger.warning(f"Failed to record activity: {e}")
 
     async def abefore_agent(
         self, state: ActivityLogState, runtime: Runtime
-    ) -> ActivityLogStateUpdate | None:
+    ) -> Optional[ActivityLogStateUpdate]:
         """在 Agent 执行前加载近期活动日志。"""
-        # 如果已经加载则跳过
-        if "activity_log_contents" in state:
-            return None
-
         contents = await self._load_recent_logs()
 
         # 趁机清理旧日志（低频操作，不影响性能）
@@ -374,33 +671,57 @@ class ActivityLogMiddleware(AgentMiddleware[ActivityLogState, ContextT, Response
         modified_request = self.modify_request(request)
         return await handler(modified_request)
 
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[Any]],
+    ) -> Any:
+        """在活动日志查询工具执行时记录聚合摘要。"""
+        tool = request.tool
+        tool_name = getattr(tool, "name", None)
+        if tool_name != QUERY_ACTIVITY_LOG_TOOL_NAME:
+            return await handler(request)
+
+        tool_call = request.tool_call or {}
+        tool_args = tool_call.get("args") or {}
+        if not isinstance(tool_args, dict):
+            tool_args = {}
+        logger.info(
+            f"开始执行活动日志查询工具: keyword={tool_args.get('keyword') or '-'}, "
+            f"date={tool_args.get('date') or '-'}"
+        )
+        if self.stream_handler and getattr(self.stream_handler, "is_streaming", False):
+            self.stream_handler.record_tool_call(
+                tool_name=QUERY_ACTIVITY_LOG_TOOL_NAME,
+                tool_message=QUERY_ACTIVITY_LOG_TOOL_DESCRIPTION,
+                tool_kwargs=tool_args,
+            )
+        try:
+            result = await handler(request)
+        except Exception as err:
+            logger.error(f"活动日志查询工具执行失败: error={err}")
+            raise
+        logger.info("活动日志查询工具执行完成")
+        return result
+
     async def aafter_agent(
         self, state: ActivityLogState, runtime: Runtime
-    ) -> dict[str, Any] | None:
-        """Agent 执行完毕后，调用 LLM 对本轮对话生成摘要并追加到当日活动日志。"""
+    ) -> Optional[dict[str, Any]]:
+        """Agent 执行完毕后，异步提交活动日志记录任务。"""
         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)
+            self._schedule_activity_recording(list(messages))
         except Exception as e:
-            logger.warning("Failed to record activity: %s", e)
+            logger.warning(f"Failed to record activity: {e}")
 
         return None
 
 
-__all__ = ["ActivityLogMiddleware"]
+__all__ = [
+    "ActivityLogMiddleware",
+    "QUERY_ACTIVITY_LOG_TOOL_NAME",
+    "load_activity_log_index",
+    "query_activity_logs",
+]

app/agent/middleware/jobs.py

@@ -128,7 +128,7 @@ def _parse_job_metadata(
 async def _alist_jobs(source_path: AsyncPath) -> list[JobMetadata]:
     """异步列出指定路径下的所有任务。
 
-    扫描包含 JOB.md 的目录并解析其元数据。
+    扫描包含 JOB.md 的目录并解析其元数据，遇到非法 UTF-8 字节时以替换字符兜底。
     """
     jobs: list[JobMetadata] = []
 
@@ -151,7 +151,10 @@ async def _alist_jobs(source_path: AsyncPath) -> list[JobMetadata]:
     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_content = await job_md_path.read_text(
+            encoding="utf-8",
+            errors="replace",
+        )
 
         # 解析元数据
         job_metadata = _parse_job_metadata(
@@ -192,7 +195,7 @@ async def load_jobs_metadata(source_paths: list[str]) -> list[JobMetadata]:
 
 JOBS_SYSTEM_PROMPT = """
 <jobs_system>
-You have a **scheduled jobs** system that allows you to track and execute long-running or recurring tasks.
+You have a scheduled jobs system for user-requested delayed or recurring work.
 
 **Jobs Location:** `{jobs_location}`
 
@@ -200,71 +203,16 @@ You have a **scheduled jobs** system that allows you to track and execute long-r
 
 {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
+Rules:
+- For new delayed, recurring, reminder, or monitoring work, use the dedicated
+  `create_agent_task`, `query_agent_tasks`, `update_agent_task`, `run_agent_task`,
+  and `delete_agent_task` tools. These tools use integer task IDs. Do not create
+  or edit JOB.md files for new tasks.
+- Use `query_schedulers` and `run_scheduler` only for MoviePilot system, plugin,
+  or workflow runtime services; never pass their string job IDs to Agent task tools.
+- Do not create tasks for immediate one-time work or work already handled by MoviePilot schedulers.
+- Entries listed above are legacy JOB.md tasks. Read their files only when a heartbeat asks you to execute them.
+- During heartbeat checks, act only on `pending` or `in_progress` jobs, update status/last_run/logs, and leave recurring jobs `pending` after each run.
 </jobs_system>
 """
 
@@ -287,7 +235,7 @@ class JobsMiddleware(AgentMiddleware[JobsState, ContextT, ResponseT]):  # noqa
     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.)"
+            return "(No active legacy JOB.md tasks. Use create_agent_task for new scheduled work.)"
 
         lines = []
         for job in jobs:
@@ -340,12 +288,7 @@ class JobsMiddleware(AgentMiddleware[JobsState, ContextT, ResponseT]):  # noqa
     ) -> JobsStateUpdate | None:
         """在 Agent 执行前异步加载任务元数据。
 
-        每个会话仅加载一次。若 state 中已有则跳过。
         """
-        # 如果 state 中已存在元数据则跳过
-        if "jobs_metadata" in state:
-            return None
-
         return JobsStateUpdate(
             jobs_metadata=await load_jobs_metadata(self.sources)
         )

app/agent/middleware/memory.py

@@ -302,7 +302,6 @@ class MemoryMiddleware(AgentMiddleware[MemoryState, ContextT, ResponseT]):  # no
         """在代理执行前扫描记忆目录并加载所有 .md 文件的内容。
 
         自动发现目录下所有 `.md` 文件并加载其内容到状态中。
-        如果状态中尚未存在则进行加载。
         同时检测记忆文件是否为空，设置 memory_empty 标志位，
         以便在系统提示词中触发初始化引导流程。
 
@@ -314,10 +313,6 @@ class MemoryMiddleware(AgentMiddleware[MemoryState, ContextT, ResponseT]):  # no
         返回：
             填充了 memory_contents 和 memory_empty 的状态更新。
         """
-        # 如果已经加载则跳过
-        if "memory_contents" in state:
-            return None
-
         # 扫描目录下所有 .md 文件
         md_files = await self._scan_memory_files()
 
@@ -335,7 +330,7 @@ class MemoryMiddleware(AgentMiddleware[MemoryState, ContextT, ResponseT]):  # no
                         MAX_MEMORY_FILE_SIZE,
                     )
                     continue
-                contents[path] = await file_path.read_text(encoding="utf-8")
+                contents[path] = await file_path.read_text(encoding="utf-8", errors="replace")
                 logger.debug("Loaded memory from: %s", path)
             except Exception as e:
                 logger.warning("Failed to read memory file %s: %s", path, e)

app/agent/middleware/patch_tool_calls.py

@@ -1,7 +1,7 @@
-from typing import Any
+from typing import Any, Optional
 
 from langchain.agents.middleware import AgentMiddleware, AgentState
-from langchain_core.messages import AIMessage, ToolMessage
+from langchain_core.messages import AIMessage, BaseMessage, ToolMessage
 from langgraph.runtime import Runtime
 from langgraph.types import Overwrite
 
@@ -9,35 +9,65 @@ 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"]
+    @staticmethod
+    def _build_cancelled_tool_message(tool_call: dict[str, Any]) -> ToolMessage:
+        """构造取消状态的工具响应消息。"""
+        tool_name = tool_call.get("name") or "unknown_tool"
+        tool_call_id = tool_call.get("id") or ""
+        tool_msg = (
+            f"Tool call {tool_name} with id {tool_call_id} was "
+            "cancelled - another message came in before it could be completed."
+        )
+        return ToolMessage(
+            content=tool_msg,
+            name=tool_name,
+            tool_call_id=tool_call_id,
+        )
+
+    @classmethod
+    def _normalize_messages(cls, messages: list[BaseMessage]) -> list[BaseMessage]:
+        """规范化工具调用消息顺序，满足 OpenAI tool_calls 协议要求。"""
         if not messages or len(messages) == 0:
+            return messages
+
+        tool_messages = {
+            msg.tool_call_id: msg
+            for msg in messages
+            if isinstance(msg, ToolMessage) and msg.tool_call_id
+        }
+        patched_messages = []
+        for msg in messages:
+            if isinstance(msg, ToolMessage):
+                continue
+
+            patched_messages.append(msg)
+            if not isinstance(msg, AIMessage) or not msg.tool_calls:
+                continue
+
+            for tool_call in msg.tool_calls:
+                tool_call_id = tool_call.get("id")
+                corresponding_tool_msg = tool_messages.get(tool_call_id)
+                if corresponding_tool_msg:
+                    patched_messages.append(corresponding_tool_msg)
+                else:
+                    patched_messages.append(cls._build_cancelled_tool_message(tool_call))
+
+        return patched_messages
+
+    def before_agent(self, state: AgentState, runtime: Runtime[Any]) -> Optional[dict[str, Any]]:  # noqa: ARG002
+        """在代理运行之前，处理任何 AIMessage 中悬空或乱序的工具调用。"""
+        messages = state["messages"]
+        patched_messages = self._normalize_messages(messages)
+        if patched_messages == messages:
             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)}
+
+    async def abefore_agent(self, state: AgentState, runtime: Runtime[Any]) -> Optional[dict[str, Any]]:  # noqa: ARG002
+        """在代理异步运行之前，处理任何 AIMessage 中悬空或乱序的工具调用。"""
+        messages = state["messages"]
+        patched_messages = self._normalize_messages(messages)
+        if patched_messages == messages:
+            return None
 
         return {"messages": Overwrite(patched_messages)}

app/agent/middleware/skills.py

@@ -1,8 +1,9 @@
+import json
 import re
 import shutil
 from collections.abc import Awaitable, Callable
 from pathlib import Path
-from typing import Annotated, List
+from typing import Annotated, Any, List, Optional
 from typing import NotRequired, TypedDict
 
 import yaml  # noqa
@@ -14,16 +15,22 @@ from langchain.agents.middleware.types import (
     ModelRequest,
     ModelResponse,
     ResponseT,
+    ToolCallRequest,
 )
 from langchain.agents.middleware.types import PrivateStateAttr  # noqa
 from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import StructuredTool
 from langgraph.runtime import Runtime
+from pydantic import BaseModel, Field
 
 from app.agent.middleware.utils import append_to_system_message
+from app.agent.tools.tags import ToolTag
 from app.log import logger
 
-# 安全提示: SKILL.md 文件最大限制为 10MB，防止 DoS 攻击
-MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024
+# 磁盘读取上限与模型返回上限分离，避免异常大的 Skill 文件撑爆内存或上下文。
+MAX_SKILL_FILE_SIZE = 1 * 1024 * 1024
+MAX_SKILL_RESULT_CHARS = 64 * 1024
+SKILL_CONTENT_TRUNCATION_SUFFIX = "\n...(Skill 内容已截断)"
 
 # Agent Skills 规范约束 (https://agentskills.io/specification)
 MAX_SKILL_NAME_LENGTH = 64
@@ -84,6 +91,15 @@ class SkillsStateUpdate(TypedDict):
     """待合并的 skill 元数据列表。"""
 
 
+class SkillToolInput(BaseModel):
+    """Skill 加载工具的输入参数模型。"""
+
+    name: str = Field(
+        ...,
+        description="Skill name or id from the available skills list.",
+    )
+
+
 def _parse_skill_metadata(  # noqa: C901
     content: str,
     skill_path: str,
@@ -234,7 +250,17 @@ async def _alist_skills(source_path: AsyncPath) -> list[SkillMetadata]:
     for skill_path in skill_dirs:
         skill_md_path = skill_path / "SKILL.md"
 
-        skill_content = await skill_md_path.read_text(encoding="utf-8")
+        stat = await skill_md_path.stat()
+        if stat.st_size > MAX_SKILL_FILE_SIZE:
+            logger.warning(
+                "Skipping %s: file too large (%d bytes)",
+                skill_md_path,
+                stat.st_size,
+            )
+            continue
+        skill_content = (await skill_md_path.read_bytes()).decode(
+            "utf-8", errors="replace"
+        )
 
         # 解析元数据
         skill_metadata = _parse_skill_metadata(
@@ -248,73 +274,72 @@ async def _alist_skills(source_path: AsyncPath) -> list[SkillMetadata]:
     return skills
 
 
+def _list_skills(source_path: Path) -> list[SkillMetadata]:
+    """同步列出指定路径下的所有技能元数据。"""
+    if not source_path.exists():
+        return []
+
+    skill_dirs = [
+        path
+        for path in source_path.iterdir()
+        if path.is_dir() and (path / "SKILL.md").is_file()
+    ]
+    if not skill_dirs:
+        return []
+
+    skill_dirs.sort(key=lambda p: p.name.casefold())
+
+    skills: list[SkillMetadata] = []
+    for skill_path in skill_dirs:
+        skill_md_path = skill_path / "SKILL.md"
+        if skill_md_path.stat().st_size > MAX_SKILL_FILE_SIZE:
+            logger.warning(
+                "Skipping %s: file too large (%d bytes)",
+                skill_md_path,
+                skill_md_path.stat().st_size,
+            )
+            continue
+        skill_content = skill_md_path.read_bytes().decode(
+            "utf-8", errors="replace"
+        )
+        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}
+You have access to a skills library for specialized MoviePilot workflows.
 
 **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!
+When the user's request matches a skill description, call the `skill` tool with that skill name before taking task actions. Follow the loaded SKILL.md instructions, and load referenced supporting files only when needed. Do not create or rewrite skills unless the user explicitly asks for skill authoring.
 </skills_system>
 """
 
+SKILL_TOOL_NAME = "skill"
+SKILL_TOOL_DESCRIPTION = """Loads the full instructions for a MoviePilot skill by name or id.
+
+Available skills:
+{skills_catalog}
+
+Call this tool when the user's task matches one of the available skills. The tool returns the SKILL.md content and metadata so you can follow the skill's instructions. Do not use this for simple tasks that do not need a skill.
+"""
+
 
 def _extract_version(skill_md: Path) -> int:
     """从 SKILL.md 文件中快速提取 version 字段，无法提取时返回 0。"""
     try:
-        content = skill_md.read_text(encoding="utf-8")
+        content = skill_md.read_text(encoding="utf-8", errors="replace")
     except Exception as err:
-        print(err)
+        logger.debug(f"读取技能版本失败: {err}")
         return 0
     match = re.match(r"^---\s*\n(.*?)\n---\s*\n", content, re.DOTALL)
     if not match:
@@ -402,6 +427,146 @@ def _sync_bundled_skills(bundled_dir: Path, target_dir: Path) -> None:
             logger.warning("更新内置技能 '%s' 失败: %s", skill_src.name, e)
 
 
+class _SkillToolProvider:
+    """Skill 工具的目录扫描和文件读取实现。"""
+
+    def __init__(self, *, sources: list[str]) -> None:
+        """初始化 Skill 工具数据源。"""
+        self._sources = sources
+
+    @staticmethod
+    def _normalize_name(value: object) -> str:
+        """标准化技能名称用于匹配。"""
+        return str(value or "").strip().casefold()
+
+    @classmethod
+    def _skill_matches(cls, skill: SkillMetadata, query: str) -> bool:
+        """判断技能元数据是否匹配用户提供的名称。"""
+        normalized_query = cls._normalize_name(query)
+        candidates = [
+            skill.get("id"),
+            skill.get("name"),
+        ]
+        return any(
+            cls._normalize_name(candidate) == normalized_query
+            for candidate in candidates
+        )
+
+    async def _find_skill(self, name: str) -> Optional[SkillMetadata]:
+        """从中间件配置的 skills 目录中查找指定技能。"""
+        all_skills: dict[str, SkillMetadata] = {}
+        for source_path in self._sources:
+            skill_source_path = AsyncPath(source_path)
+            if not await skill_source_path.exists():
+                continue
+            for skill in await _alist_skills(skill_source_path):
+                all_skills[skill["name"]] = skill
+
+        for skill in all_skills.values():
+            if self._skill_matches(skill, name):
+                return skill
+        return None
+
+    @staticmethod
+    async def _read_skill_content(skill_path: str) -> tuple[str, bool]:
+        """读取技能文件内容，并在超出上限时返回截断标记。"""
+        path = AsyncPath(skill_path)
+        stat = await path.stat()
+        truncated = stat.st_size > MAX_SKILL_FILE_SIZE
+        async with await path.open("rb") as handle:
+            raw_content = await handle.read(MAX_SKILL_FILE_SIZE)
+        return raw_content.decode("utf-8", errors="replace"), truncated
+
+    @staticmethod
+    def _serialize_skill_payload(payload: dict[str, Any]) -> str:
+        """序列化 Skill 返回值，并严格限制最终进入模型的字符数。"""
+        serialized = json.dumps(payload, ensure_ascii=False, indent=2)
+        if len(serialized) <= MAX_SKILL_RESULT_CHARS:
+            return serialized
+
+        original_content = str(payload.get("content") or "")
+        truncated_payload = dict(payload)
+        truncated_payload["truncated"] = True
+        low = 0
+        high = len(original_content)
+        best_result = json.dumps(
+            {
+                **truncated_payload,
+                "content": SKILL_CONTENT_TRUNCATION_SUFFIX.strip(),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+        while low <= high:
+            middle = (low + high) // 2
+            candidate = json.dumps(
+                {
+                    **truncated_payload,
+                    "content": (
+                        original_content[:middle]
+                        + SKILL_CONTENT_TRUNCATION_SUFFIX
+                    ),
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+            if len(candidate) <= MAX_SKILL_RESULT_CHARS:
+                best_result = candidate
+                low = middle + 1
+            else:
+                high = middle - 1
+        return best_result
+
+    async def load_skill(self, name: str) -> str:
+        """加载指定 Skill 的完整说明并返回 JSON 字符串。"""
+        logger.info(f"加载 Skill: name={name}")
+        try:
+            skill = await self._find_skill(name)
+            if not skill:
+                return json.dumps(
+                    {
+                        "success": False,
+                        "message": f"未找到 Skill: {name}",
+                    },
+                    ensure_ascii=False,
+                )
+
+            content, truncated = await self._read_skill_content(skill["path"])
+            return self._serialize_skill_payload(
+                {
+                    "success": True,
+                    "skill": {
+                        "id": skill.get("id"),
+                        "name": skill.get("name"),
+                        "description": skill.get("description"),
+                        "path": skill.get("path"),
+                        "allowed_tools": skill.get("allowed_tools", []),
+                    },
+                    "content": content,
+                    "truncated": truncated,
+                }
+            )
+        except Exception as err:
+            logger.error(f"加载 Skill 失败: {err}", exc_info=True)
+            return json.dumps(
+                {
+                    "success": False,
+                    "message": f"加载 Skill 时发生错误: {str(err)}",
+                },
+                ensure_ascii=False,
+            )
+
+
+def _format_skill_tool_catalog(skills: list[SkillMetadata]) -> str:
+    """渲染 Skill 工具描述中的可用技能目录。"""
+    if not skills:
+        return "(No skills are currently available.)"
+    return "\n".join(
+        f"- {skill['id']}: {skill['name']} - {skill['description']}"
+        for skill in skills
+    )
+
+
 class SkillsMiddleware(AgentMiddleware[SkillsState, ContextT, ResponseT]):  # noqa
     """加载并向系统提示词注入 Agent Skill 的中间件。
 
@@ -416,6 +581,7 @@ class SkillsMiddleware(AgentMiddleware[SkillsState, ContextT, ResponseT]):  # no
         *,
         sources: list[str],
         bundled_skills_dir: str | None = None,
+        stream_handler: Optional[Any] = None,
     ) -> None:
         """初始化 Skill 中间件。
 
@@ -426,26 +592,63 @@ class SkillsMiddleware(AgentMiddleware[SkillsState, ContextT, ResponseT]):  # no
         bundled_skills_dir : str | None
             项目内置技能目录路径。若提供，在首次加载前会将其中不存在于
             sources 首个目录的技能自动复制过去。
+        stream_handler : Optional[Any]
+            流式输出处理器，用于记录 skill 工具调用摘要。
         """
         self.sources = sources
         self.bundled_skills_dir = bundled_skills_dir
+        self.stream_handler = stream_handler
         self.system_prompt_template = SKILLS_SYSTEM_PROMPT
+        self._skill_provider = _SkillToolProvider(sources=sources)
+        self.tools = [
+            StructuredTool.from_function(
+                coroutine=self._skill_provider.load_skill,
+                name=SKILL_TOOL_NAME,
+                description=SKILL_TOOL_DESCRIPTION.format(
+                    skills_catalog=_format_skill_tool_catalog(
+                        self._load_skills_metadata()
+                    )
+                ),
+                args_schema=SkillToolInput,
+                tags=[ToolTag.Read, ToolTag.Skill],
+            )
+        ]
 
-    def _format_skills_locations(self) -> str:
-        """格式化技能位置信息用于系统提示词。"""
-        locations = []
+    def _sync_bundled_skills(self) -> None:
+        """将项目内置 Skill 同步到首个用户技能目录。"""
+        if not self.bundled_skills_dir or not self.sources:
+            return
+        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)
 
-        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}")
+    def _load_skills_metadata(self) -> list[SkillMetadata]:
+        """同步加载当前配置目录中的 Skill 元数据。"""
+        self._sync_bundled_skills()
+        all_skills: dict[str, SkillMetadata] = {}
+        for source_path in self.sources:
+            for skill in _list_skills(Path(source_path)):
+                all_skills[skill["name"]] = skill
+        return list(all_skills.values())
 
-        return "\n".join(locations)
+    def _refresh_skill_tool_description(
+        self, skills: list[SkillMetadata]
+    ) -> None:
+        """刷新 skill 工具描述中的可用技能目录。"""
+        if not self.tools:
+            return
+        self.tools[0].description = SKILL_TOOL_DESCRIPTION.format(
+            skills_catalog=_format_skill_tool_catalog(skills)
+        )
 
-    def _format_skills_list(self, skills: list[SkillMetadata]) -> str:
+    @staticmethod
+    def _format_skills_list(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)})"
+            return "(No skills available yet.)"
 
         lines = []
         for skill in skills:
@@ -456,18 +659,15 @@ class SkillsMiddleware(AgentMiddleware[SkillsState, ContextT, ResponseT]):  # no
             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,
         )
 
@@ -482,21 +682,9 @@ class SkillsMiddleware(AgentMiddleware[SkillsState, ContextT, ResponseT]):  # no
     ) -> 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)
+        self._sync_bundled_skills()
 
         all_skills: dict[str, SkillMetadata] = {}
 
@@ -511,6 +699,7 @@ class SkillsMiddleware(AgentMiddleware[SkillsState, ContextT, ResponseT]):  # no
                 all_skills[skill["name"]] = skill
 
         skills = list(all_skills.values())
+        self._refresh_skill_tool_description(skills)
         return SkillsStateUpdate(skills_metadata=skills)
 
     async def awrap_model_call(
@@ -524,5 +713,37 @@ class SkillsMiddleware(AgentMiddleware[SkillsState, ContextT, ResponseT]):  # no
         modified_request = self.modify_request(request)
         return await handler(modified_request)
 
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[Any]],
+    ) -> Any:
+        """在 skill 工具执行时记录聚合摘要。"""
+        tool = request.tool
+        tool_name = getattr(tool, "name", None)
+        if tool_name != SKILL_TOOL_NAME:
+            return await handler(request)
 
-__all__ = ["SkillMetadata", "SkillsMiddleware"]
+        tool_call = request.tool_call or {}
+        tool_args = tool_call.get("args") or {}
+        if not isinstance(tool_args, dict):
+            tool_args = {}
+        logger.info(
+            f"开始执行 Skill 工具: name={tool_args.get('name') or '-'}"
+        )
+        if self.stream_handler and getattr(self.stream_handler, "is_streaming", False):
+            self.stream_handler.record_tool_call(
+                tool_name=SKILL_TOOL_NAME,
+                tool_message="Skill loaded",
+                tool_kwargs=tool_args,
+            )
+        try:
+            result = await handler(request)
+        except Exception as err:
+            logger.error(f"Skill 工具执行失败: error={err}")
+            raise
+        logger.info("Skill 工具执行完成")
+        return result
+
+
+__all__ = ["SKILL_TOOL_NAME", "SkillMetadata", "SkillsMiddleware"]

app/agent/middleware/tool_selection.py

@@ -1,5 +1,6 @@
 """MoviePilot 自定义工具筛选中间件。"""
 
+from dataclasses import dataclass, replace
 import json
 from collections.abc import Awaitable, Callable
 from typing import Annotated, Any, NotRequired
@@ -19,13 +20,40 @@ from langchain.agents.middleware.tool_selection import (
     LLMToolSelectorMiddleware,
 )
 from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
 from langchain_core.runnables import RunnableConfig
 from langchain_core.tools import BaseTool
 from langgraph.runtime import Runtime
 from typing_extensions import TypedDict  # noqa
 
+from app.agent.llm import LLMHelper
+from app.agent.tools.tags import ToolTag
 from app.log import logger
 
+MIN_SELECTED_TOOL_COUNT = 4
+RECENT_SELECTION_CONTEXT_MESSAGE_LIMIT = 6
+RECENT_SELECTION_CONTEXT_MAX_CHARS = 6000
+RECENT_SELECTION_CONTEXT_TRUNCATION_PREFIX = "..."
+TOOL_GROUP_EXCLUDED_TAGS = frozenset(
+    {
+        ToolTag.AgentTool.value,
+        ToolTag.Read.value,
+        ToolTag.Write.value,
+        ToolTag.Admin.value,
+        ToolTag.Message.value,
+        ToolTag.UserInteraction.value,
+        ToolTag.TerminalResponse.value,
+    }
+)
+
+MOVIEPILOT_TOOL_SELECTION_HINT = """
+
+MoviePilot tool-chain hints:
+- Tools with the same capability tag belong to the same functional group.
+- For multi-step MoviePilot tasks, keep same-tag tools together when relevant.
+- Prefer selecting likely next-step tools in the same capability group instead of selecting only the first tool.
+"""
+
 
 class ToolSelectionState(AgentState):
     """工具筛选中间件私有状态。"""
@@ -40,19 +68,25 @@ class ToolSelectionStateUpdate(TypedDict):
     selected_tool_names: list[str] | None
 
 
+@dataclass(frozen=True)
+class _ToolSelectionAttempt:
+    """工具筛选尝试结果，用于统一记录最终日志。"""
+
+    request: ModelRequest
+    selected_tool_names: list[str]
+    status: str
+    detail: str = ""
+
+
 class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
     """
-    为 DeepSeek 兼容端点提供更稳妥的工具筛选实现。
+    使用 provider-neutral JSON 提示执行工具筛选。
 
-    LangChain 默认会通过 `with_structured_output()` 走 OpenAI 的
-    `response_format=json_schema` 路径，但 DeepSeek 官方 OpenAI 兼容端点公开文档
-    仅保证 `json_object` 模式可用。对于 `deepseek-reasoner`，这会在工具筛选阶段
-    提前触发 400，导致 Agent 还没真正开始执行工具就失败。
-
-    因此这里仅在识别到 DeepSeek 模型/端点时，退回到显式 JSON 输出模式：
-    1. 使用 `response_format={"type": "json_object"}`；
-    2. 在提示词中明确约束返回 JSON 结构；
-    3. 手动解析 `{"tools": [...]}`，其余模型继续沿用 LangChain 默认实现。
+    LangChain 默认会通过 `with_structured_output()` 走 provider-specific 的
+    结构化输出能力，不同 OpenAI/Anthropic 兼容端点对 `response_format`、
+    JSON schema 和工具绑定的支持并不一致。工具筛选只是 Agent 执行前的
+    辅助优化，失败时也会恢复使用全部工具，因此这里统一使用文本提示约束
+    模型返回 `{"tools": [...]}` 并手动解析，避免在筛选阶段引入额外兼容分支。
 
     另外，LangChain 原生工具筛选挂在 `wrap_model_call` 上，会在同一条用户请求
     的每次“模型回合”前都重新筛选一次工具。对于会多轮调用工具的复杂任务，
@@ -73,12 +107,219 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
     ) -> None:
         super().__init__(
             model=model,
-            system_prompt=system_prompt,
+            system_prompt=self._append_tool_selection_hint(system_prompt),
             max_tools=max_tools,
             always_include=always_include,
         )
         self.selection_tools = selection_tools or []
 
+    @classmethod
+    def _render_recent_conversation_context(
+            cls,
+            messages: list[Any],
+    ) -> tuple[str, int]:
+        """渲染最近对话上下文，供工具筛选模型理解多轮追问。"""
+        rendered_messages = []
+        for message in messages:
+            if isinstance(message, HumanMessage):
+                role = "User"
+            elif isinstance(message, AIMessage):
+                role = "Assistant"
+            else:
+                continue
+
+            content = LLMHelper.extract_text_content(message.content).strip()
+            if not content:
+                continue
+            rendered_messages.append(f"{role}: {content}")
+
+        recent_messages = rendered_messages[-RECENT_SELECTION_CONTEXT_MESSAGE_LIMIT:]
+        context = "\n\n".join(recent_messages)
+        if len(context) > RECENT_SELECTION_CONTEXT_MAX_CHARS:
+            context = (
+                f"{RECENT_SELECTION_CONTEXT_TRUNCATION_PREFIX}"
+                f"{context[-RECENT_SELECTION_CONTEXT_MAX_CHARS:]}"
+            )
+        return context, len(recent_messages)
+
+    @classmethod
+    def _build_contextual_user_message(
+            cls,
+            messages: list[Any],
+            last_user_message: HumanMessage,
+    ) -> HumanMessage:
+        """根据最近对话构造工具筛选专用用户消息。"""
+        context, message_count = cls._render_recent_conversation_context(messages)
+        if message_count <= 1:
+            return last_user_message
+
+        return HumanMessage(
+            content=(
+                "Recent conversation context for tool selection:\n"
+                f"{context}\n\n"
+                "Select tools for the latest user instruction. Use prior assistant "
+                "messages and earlier user requests when the latest user message "
+                "depends on previous context."
+            )
+        )
+
+    def _prepare_selection_request(
+            self,
+            request: ModelRequest[ContextT],
+    ) -> Any | None:
+        """准备带最近对话上下文的工具筛选请求。"""
+        selection_request = super()._prepare_selection_request(request)
+        if selection_request is None:
+            return None
+
+        contextual_user_message = self._build_contextual_user_message(
+            messages=request.messages,
+            last_user_message=selection_request.last_user_message,
+        )
+        if contextual_user_message is selection_request.last_user_message:
+            return selection_request
+        return replace(selection_request, last_user_message=contextual_user_message)
+
+    @staticmethod
+    def _append_tool_selection_hint(system_prompt: str) -> str:
+        """追加 MoviePilot 工具组选择提示，避免复杂链路只选中首个工具。"""
+        if "MoviePilot tool-chain hints:" in system_prompt:
+            return system_prompt
+        return f"{system_prompt.rstrip()}{MOVIEPILOT_TOOL_SELECTION_HINT}"
+
+    def _get_tool_selection_limit(self, valid_tool_names: list[str]) -> int:
+        """计算补齐筛选结果时允许使用的工具数量上限。"""
+        if self.max_tools:
+            return min(self.max_tools, len(valid_tool_names))
+        return len(valid_tool_names)
+
+    @staticmethod
+    def _normalize_tool_tags(tool: BaseTool) -> list[str]:
+        """读取工具的业务标签，过滤掉无法表达工具组的通用标签。"""
+        tags = getattr(tool, "tags", None) or []
+        if isinstance(tags, str):
+            tags = [tags]
+
+        normalized_tags = []
+        for tag in tags:
+            tag_value = getattr(tag, "value", tag)
+            if not tag_value:
+                continue
+            tag_name = str(tag_value)
+            if tag_name in TOOL_GROUP_EXCLUDED_TAGS or tag_name in normalized_tags:
+                continue
+            normalized_tags.append(tag_name)
+        return normalized_tags
+
+    @classmethod
+    def _build_tool_groups(
+            cls,
+            available_tools: list[BaseTool],
+            valid_tool_names: list[str],
+    ) -> list[tuple[str, list[str]]]:
+        """根据工具标签构造能力组，保留当前工具列表中的稳定顺序。"""
+        valid_tool_set = set(valid_tool_names)
+        tool_groups: dict[str, list[str]] = {}
+        for tool in available_tools:
+            tool_name = getattr(tool, "name", None)
+            if not tool_name or tool_name not in valid_tool_set:
+                continue
+            for tag in cls._normalize_tool_tags(tool):
+                group_tool_names = tool_groups.setdefault(tag, [])
+                if tool_name not in group_tool_names:
+                    group_tool_names.append(tool_name)
+
+        return [
+            (tag, tool_names)
+            for tag, tool_names in tool_groups.items()
+            if len(tool_names) > 1
+        ]
+
+    @classmethod
+    def _get_matched_tool_groups(
+            cls,
+            selected_names: list[str],
+            available_tools: list[BaseTool],
+            valid_tool_names: list[str],
+    ) -> list[tuple[str, list[str]]]:
+        """返回已选工具命中的标签能力组。"""
+        groups_by_tag = {
+            tag: tool_names
+            for tag, tool_names in cls._build_tool_groups(
+                available_tools=available_tools,
+                valid_tool_names=valid_tool_names,
+            )
+        }
+        tools_by_name = {
+            tool.name: tool
+            for tool in available_tools
+            if getattr(tool, "name", None)
+        }
+        matched_groups: list[tuple[str, list[str]]] = []
+        seen_tags = set()
+        for tool_name in selected_names:
+            tool = tools_by_name.get(tool_name)
+            if not tool:
+                continue
+            for tag in cls._normalize_tool_tags(tool):
+                if tag in seen_tags or tag not in groups_by_tag:
+                    continue
+                matched_groups.append((tag, groups_by_tag[tag]))
+                seen_tags.add(tag)
+        return matched_groups
+
+    def _complete_low_count_selection(
+            self,
+            selected_tool_names: list[str],
+            valid_tool_names: list[str],
+            available_tools: list[BaseTool],
+    ) -> list[str]:
+        """
+        当模型只选出极少工具时，按工具标签补齐同组工具。
+
+        工具标签是工具自身声明的能力归属。这里只补齐已经命中的标签组，
+        不会把所有工具组都展开。
+        """
+        limit = self._get_tool_selection_limit(valid_tool_names)
+        selected_names = [
+            tool_name
+            for tool_name in selected_tool_names
+            if tool_name in valid_tool_names
+        ]
+        selected_set = set(selected_names)
+        valid_tool_set = set(valid_tool_names)
+        completed_names = list(selected_names)
+        matched_groups = self._get_matched_tool_groups(
+            selected_names=selected_names,
+            available_tools=available_tools,
+            valid_tool_names=valid_tool_names,
+        )
+        if not matched_groups:
+            return completed_names[:limit]
+
+        matched_group_tool_names = {
+            tool_name
+            for _, group_tool_names in matched_groups
+            for tool_name in group_tool_names
+        }
+        target_count = min(
+            max(MIN_SELECTED_TOOL_COUNT, len(matched_group_tool_names)),
+            limit,
+        )
+        if len(selected_names) >= target_count:
+            return selected_names[:limit]
+
+        for _, group_tool_names in matched_groups:
+            for tool_name in group_tool_names:
+                if tool_name in selected_set or tool_name not in valid_tool_set:
+                    continue
+                completed_names.append(tool_name)
+                selected_set.add(tool_name)
+                if len(completed_names) >= target_count:
+                    return completed_names[:limit]
+
+        return completed_names[:limit]
+
     def _process_selection_response(
             self,
             response: dict[str, Any],
@@ -87,96 +328,41 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
             request: ModelRequest[ContextT],
     ) -> ModelRequest[ContextT]:
         """
-        处理工具筛选响应，并保留空结果回退所有工具的 MoviePilot 策略。
+        处理工具筛选响应，并在正常空结果时禁用可筛选工具。
         """
         if response.get("tools") == []:
-            logger.warning("工具筛选结果为空，将恢复使用所有工具。")
-
             always_included_tools: list[BaseTool] = [
                 tool
                 for tool in request.tools
                 if not isinstance(tool, dict) and tool.name in self.always_include
             ]
             provider_tools = [tool for tool in request.tools if isinstance(tool, dict)]
+            return request.override(tools=[*always_included_tools, *provider_tools])
 
-            return request.override(
-                tools=[*available_tools, *always_included_tools, *provider_tools]
-            )
-
-        return super()._process_selection_response(
+        response["tools"] = self._complete_low_count_selection(
+            selected_tool_names=[
+                tool_name
+                for tool_name in response.get("tools", [])
+                if isinstance(tool_name, str)
+            ],
+            valid_tool_names=valid_tool_names,
+            available_tools=available_tools,
+        )
+        modified_request = super()._process_selection_response(
             response,
             available_tools,
             valid_tool_names,
             request,
         )
-
-    @staticmethod
-    def _is_deepseek_compatible_model(model: BaseChatModel) -> bool:
-        """
-        判断当前模型是否应当走 DeepSeek JSON 兼容分支。
-
-        除了官方 `langchain_deepseek`，用户也可能通过 OpenAI-compatible
-        配置把 DeepSeek 端点接到 `ChatOpenAI`。因此这里同时检查模块名、模型名
-        和 Base URL，避免只靠单一条件漏判。
-        """
-        module_name = type(model).__module__.lower()
-        model_name = (
-            str(getattr(model, "model_name", "") or getattr(model, "model", ""))
-            .strip()
-            .lower()
-        )
-        base_url = (
-            str(getattr(model, "openai_api_base", "") or getattr(model, "api_base", ""))
-            .strip()
-            .lower()
-        )
-
-        return (
-                "deepseek" in module_name
-                or model_name.startswith("deepseek-")
-                or "api.deepseek.com" in base_url
-        )
-
-    @staticmethod
-    def _extract_text_content(content: Any) -> str:
-        """
-        从模型响应中提取纯文本。
-
-        这里不依赖上层 LLMHelper，避免中间件与 LLM 构造逻辑互相耦合。
-        """
-        if content is None:
-            return ""
-        if isinstance(content, str):
-            return content
-        if isinstance(content, list):
-            text_parts: list[str] = []
-            for block in content:
-                if isinstance(block, str):
-                    text_parts.append(block)
-                    continue
-                if isinstance(block, dict):
-                    if block.get("type") == "text" and isinstance(
-                            block.get("text"), str
-                    ):
-                        text_parts.append(block["text"])
-                        continue
-                    if not block.get("type") and isinstance(block.get("text"), str):
-                        text_parts.append(block["text"])
-            return "".join(text_parts)
-        if isinstance(content, dict):
-            if content.get("type") == "text" and isinstance(content.get("text"), str):
-                return content["text"]
-            if not content.get("type") and isinstance(content.get("text"), str):
-                return content["text"]
-        return ""
+        return modified_request
 
     @staticmethod
     def _parse_json_object(text: str) -> dict[str, Any]:
         """
         解析模型返回的 JSON。
 
-        DeepSeek 在 JSON 模式下通常会返回纯 JSON，但这里仍做一层兜底，
-        兼容模型偶发输出围栏或前后说明文本的情况。
+        不同模型可能偶发输出 Markdown 围栏或前后说明文本，因此这里从
+        响应中提取第一个 JSON 对象作为兜底。
         """
         stripped_text = text.strip()
         if not stripped_text:
@@ -199,23 +385,46 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
             raise ValueError("工具筛选 JSON 顶层必须是对象")
         return payload
 
-    @staticmethod
-    def _render_tool_list(available_tools: list[Any]) -> str:
+    @classmethod
+    def _render_tool_list(cls, available_tools: list[Any]) -> str:
         """把工具名和描述渲染成稳定的文本列表。"""
-        return "\n".join(
-            f"- {tool.name}: {tool.description}" for tool in available_tools
+        lines = []
+        for tool in available_tools:
+            tags = cls._normalize_tool_tags(tool)
+            tag_text = f" [group tags: {', '.join(tags)}]" if tags else ""
+            lines.append(f"- {tool.name}{tag_text}: {tool.description}")
+        return "\n".join(lines)
+
+    @classmethod
+    def _render_tool_groups(cls, available_tools: list[BaseTool]) -> str:
+        """把当前可用工具按标签渲染成能力组提示。"""
+        valid_tool_names = [
+            tool.name
+            for tool in available_tools
+            if getattr(tool, "name", None)
+        ]
+        groups = cls._build_tool_groups(
+            available_tools=available_tools,
+            valid_tool_names=valid_tool_names,
         )
+        if not groups:
+            return ""
+        rendered_groups = "\n".join(
+            f"- {tag}: {', '.join(tool_names)}"
+            for tag, tool_names in groups
+        )
+        return f"Capability groups from tool tags:\n{rendered_groups}\n\n"
 
-    def _build_deepseek_selection_prompt(self, selection_request: Any) -> str:
+    def _build_json_selection_prompt(self, selection_request: Any) -> str:
         """
-        为 DeepSeek 生成显式 JSON 输出提示。
+        生成显式 JSON 输出提示。
 
-        DeepSeek 官方文档要求在 JSON 输出模式下，提示词中必须明确包含 JSON
-        约束，否则兼容端点可能返回空内容或无意义输出。
+        使用纯提示约束可覆盖更多兼容端点，避免在工具筛选阶段依赖某个
+        provider 专属的 `response_format` 或 schema 能力。
         """
         limit_instruction = ""
         if self.max_tools:
-            limit_instruction = f"- Select up to {self.max_tools} tools. IF NO TOOLS ARE RELEVANT, DO NOT RETURN AN EMPTY ARRAY. SELECT THE MOST APPLICABLE ONES TO ENSURE THE REQUEST IS HANDLED."
+            limit_instruction = f"- Select up to {self.max_tools} tools. Return an empty array if no tools are relevant."
 
         return (
             f"{selection_request.system_message}\n\n"
@@ -225,18 +434,20 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
             "- The `tools` field must be a JSON array of strings.\n"
             "- Only use tool names from the allowed list below.\n"
             "- Order tools by relevance, with the most relevant first.\n"
+            "- Tools sharing the same capability tag are in the same group; include same-group tools together when relevant.\n"
             f"{limit_instruction}\n"
             "- Do not add explanations, markdown, or extra keys.\n\n"
+            f"{self._render_tool_groups(selection_request.available_tools)}"
             "Allowed tools:\n"
             f"{self._render_tool_list(selection_request.available_tools)}"
         )
 
     def _normalize_selection_response(self, response: Any) -> dict[str, list[str]]:
         """
-        解析并标准化 DeepSeek JSON 模式的工具筛选结果。
+        解析并标准化显式 JSON 模式的工具筛选结果。
         """
         content = getattr(response, "content", response)
-        text = self._extract_text_content(content)
+        text = LLMHelper.extract_text_content(content)
         logger.debug(f"工具筛选原始响应: {text}")
         payload = self._parse_json_object(text)
 
@@ -250,22 +461,21 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
         logger.debug(f"工具筛选标准化结果: {normalized_tools}")
         return {"tools": normalized_tools}
 
-    async def _aselect_tools_with_deepseek(
+    async def _aselect_tools_with_json_prompt(
             self, selection_request: Any
     ) -> dict[str, list[str]]:
         """
-        使用 DeepSeek 兼容的 JSON 输出模式执行异步工具筛选。
+        使用 JSON 提示执行异步工具筛选。
+
+        :param selection_request: LangChain 工具筛选请求
+        :return: 标准化后的工具名列表
         """
-        logger.debug("工具筛选走 DeepSeek JSON 兼容分支")
-        structured_model = selection_request.model.bind(
-            response_format={"type": "json_object"}
-        )
-        response = await structured_model.ainvoke(
+        logger.debug("工具筛选走 JSON 提示分支")
+        response = await selection_request.model.ainvoke(
             [
-                {
-                    "role": "system",
-                    "content": self._build_deepseek_selection_prompt(selection_request),
-                },
+                SystemMessage(
+                    content=self._build_json_selection_prompt(selection_request)
+                ),
                 selection_request.last_user_message,
             ]
         )
@@ -276,6 +486,31 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
         """从已筛选后的请求中提取最终工具名，保留原有顺序。"""
         return [tool.name for tool in request.tools if not isinstance(tool, dict)]
 
+    @staticmethod
+    def _count_request_tools(request: ModelRequest) -> int:
+        """统计当前请求中的 LangChain 工具数量，不包含 provider 原生工具字典。"""
+        return len([tool for tool in request.tools if not isinstance(tool, dict)])
+
+    @classmethod
+    def _log_selection_attempt(cls, attempt: _ToolSelectionAttempt) -> None:
+        """按工具筛选最终状态记录稳定日志。"""
+        tool_count = cls._count_request_tools(attempt.request)
+        if attempt.status == "selected":
+            selected_text = ", ".join(attempt.selected_tool_names) or "无有效工具"
+            logger.info(f"工具筛选结果: {selected_text}")
+            return
+        if attempt.status == "failed_fallback":
+            logger.warning(
+                f"工具筛选失败，将恢复使用所有工具（共 {tool_count} 个）: {attempt.detail}"
+            )
+            return
+        if attempt.status == "skipped":
+            logger.info(f"工具筛选跳过: {attempt.detail}。")
+            return
+        if attempt.status == "reused":
+            selected_text = ", ".join(attempt.selected_tool_names) or "无有效工具"
+            logger.info(f"工具筛选复用已有结果: {selected_text}")
+
     @staticmethod
     def _apply_selected_tools(
             request: ModelRequest[ContextT],
@@ -287,9 +522,6 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
         这里只复用首次筛选出的客户端工具名；provider-specific 的 dict 工具仍然
         原样保留，避免破坏 LangChain/provider 自身的工具绑定约定。
         """
-        if not selected_tool_names:
-            return request
-
         current_tools_by_name = {
             tool.name: tool for tool in request.tools if not isinstance(tool, dict)
         }
@@ -310,30 +542,43 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
         这里单独抽成 helper，便于首次筛选后缓存结果，也便于测试覆盖
         “首轮筛选，后续复用”的行为。
         """
+        return (await self._aselect_request_once_with_status(request)).request
+
+    async def _aselect_request_once_with_status(
+            self, request: ModelRequest[ContextT]
+    ) -> _ToolSelectionAttempt:
+        """
+        执行一次真实工具筛选，并携带最终状态供调用方统一记录日志。
+        """
         selection_request = self._prepare_selection_request(request)
         if selection_request is None:
-            return request
+            return _ToolSelectionAttempt(
+                request=request,
+                selected_tool_names=self._extract_selected_tool_names(request),
+                status="skipped",
+                detail="没有需要筛选的工具",
+            )
 
-        if not self._is_deepseek_compatible_model(selection_request.model):
-            captured_request: ModelRequest[ContextT] = request
-
-            async def _capture_handler(
-                    updated_request: ModelRequest[ContextT],
-            ) -> ModelRequest[ContextT]:
-                nonlocal captured_request
-                captured_request = updated_request
-                return updated_request
-
-            await super().awrap_model_call(request, _capture_handler)
-            return captured_request
-
-        response = await self._aselect_tools_with_deepseek(selection_request)
-        return self._process_selection_response(
-            response,
-            selection_request.available_tools,
-            selection_request.valid_tool_names,
-            request,
-        )
+        try:
+            response = await self._aselect_tools_with_json_prompt(selection_request)
+            modified_request = self._process_selection_response(
+                response,
+                selection_request.available_tools,
+                selection_request.valid_tool_names,
+                request,
+            )
+            return _ToolSelectionAttempt(
+                request=modified_request,
+                selected_tool_names=self._extract_selected_tool_names(modified_request),
+                status="selected",
+            )
+        except Exception as err:
+            return _ToolSelectionAttempt(
+                request=request,
+                selected_tool_names=self._extract_selected_tool_names(request),
+                status="failed_fallback",
+                detail=str(err),
+            )
 
     async def abefore_agent(  # noqa
             self,
@@ -347,10 +592,22 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
         这样后续多轮 `model -> tools -> model` 循环都只复用这一次结果，
         不会为每次模型回合重复追加一笔 selector LLM 开销。
         """
-        if "selected_tool_names" in state:
-            return None
-
         if not self.selection_tools or self.model is None:
+            detail = "没有可筛选工具" if not self.selection_tools else "未配置筛选模型"
+            self._log_selection_attempt(
+                _ToolSelectionAttempt(
+                    request=ModelRequest(
+                        model=self.model,
+                        tools=list(self.selection_tools),
+                        messages=state["messages"],
+                        state=state,
+                        runtime=runtime,
+                    ),
+                    selected_tool_names=[],
+                    status="skipped",
+                    detail=detail,
+                )
+            )
             return ToolSelectionStateUpdate(selected_tool_names=None)
 
         selection_request = ModelRequest(
@@ -360,9 +617,10 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
             state=state,
             runtime=runtime,
         )
-        modified_request = await self._aselect_request_once(selection_request)
-        selected_tool_names = self._extract_selected_tool_names(modified_request)
-        return ToolSelectionStateUpdate(selected_tool_names=selected_tool_names or None)
+        attempt = await self._aselect_request_once_with_status(selection_request)
+        self._log_selection_attempt(attempt)
+        selected_tool_names = attempt.selected_tool_names
+        return ToolSelectionStateUpdate(selected_tool_names=selected_tool_names)
 
     async def awrap_model_call(
             self,
@@ -383,11 +641,13 @@ class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
                 and self.selection_tools
                 and self.model is not None
         ):
-            request = await self._aselect_request_once(request)
-            selected_tool_names = self._extract_selected_tool_names(request) or None
+            attempt = await self._aselect_request_once_with_status(request)
+            self._log_selection_attempt(attempt)
+            request = attempt.request
+            selected_tool_names = attempt.selected_tool_names
             request.state["selected_tool_names"] = selected_tool_names  # noqa
 
-        if selected_tool_names:
+        if selected_tool_names is not None:
             request = self._apply_selected_tools(request, selected_tool_names)
 
         return await handler(request)

app/agent/middleware/usage.py

@@ -51,6 +51,18 @@ class UsageMiddleware(AgentMiddleware):
 
         return None
 
+    @classmethod
+    def _first_int(
+        cls,
+        candidates: tuple[tuple[Any, tuple[str, ...]], ...],
+    ) -> int | None:
+        """按优先级返回首个可用的 usage 整数值。"""
+        for container, keys in candidates:
+            value = cls._lookup_int(container, *keys)
+            if value is not None:
+                return value
+        return None
+
     @classmethod
     def _extract_model_name(cls, model: Any) -> str | None:
         return (
@@ -82,6 +94,131 @@ class UsageMiddleware(AgentMiddleware):
             or {}
         )
 
+        input_token_details = None
+        if usage_metadata:
+            getter = getattr(usage_metadata, "get", None)
+            input_token_details = (
+                getter("input_token_details")
+                if callable(getter)
+                else getattr(usage_metadata, "input_token_details", None)
+            )
+
+        cache_read_tokens = cls._first_int(
+            (
+                (
+                    input_token_details,
+                    (
+                        "cache_read",
+                        "cached_tokens",
+                        "cache_read_input_tokens",
+                        "cacheReadInputTokens",
+                    ),
+                ),
+                (
+                    token_usage,
+                    (
+                        "prompt_cache_hit_tokens",
+                        "cache_read_input_tokens",
+                        "cacheReadInputTokens",
+                    ),
+                ),
+                (
+                    response_metadata,
+                    (
+                        "prompt_cache_hit_tokens",
+                        "cache_read_input_tokens",
+                        "cacheReadInputTokens",
+                        "cached_tokens",
+                    ),
+                ),
+            )
+        )
+        if cache_read_tokens is None:
+            cache_read_tokens = cls._first_int(
+                (
+                    (
+                        token_usage.get("prompt_tokens_details", {}),
+                        ("cached_tokens", "cache_read"),
+                    ),
+                    (
+                        token_usage.get("input_tokens_details", {}),
+                        ("cached_tokens", "cache_read"),
+                    ),
+                )
+            )
+
+        cache_write_tokens = cls._first_int(
+            (
+                (
+                    input_token_details,
+                    (
+                        "cache_creation",
+                        "cache_write",
+                        "cache_write_tokens",
+                        "cache_write_input_tokens",
+                        "cacheWriteInputTokens",
+                    ),
+                ),
+                (
+                    token_usage,
+                    (
+                        "cache_creation_input_tokens",
+                        "cache_write_tokens",
+                        "cache_write_input_tokens",
+                        "cacheWriteInputTokens",
+                    ),
+                ),
+                (
+                    response_metadata,
+                    (
+                        "cache_creation_input_tokens",
+                        "cache_write_tokens",
+                        "cache_write_input_tokens",
+                        "cacheWriteInputTokens",
+                    ),
+                ),
+            )
+        )
+        if cache_write_tokens is None:
+            cache_write_tokens = cls._first_int(
+                (
+                    (
+                        token_usage.get("prompt_tokens_details", {}),
+                        ("cache_write_tokens", "cache_creation"),
+                    ),
+                    (
+                        token_usage.get("input_tokens_details", {}),
+                        ("cache_write_tokens", "cache_creation"),
+                    ),
+                )
+            )
+        cache_write_ttl_tokens = sum(
+            cls._lookup_int(
+                input_token_details,
+                ttl_key,
+            )
+            or 0
+            for ttl_key in (
+                "ephemeral_5m_input_tokens",
+                "ephemeral_1h_input_tokens",
+            )
+        )
+        if cache_write_ttl_tokens:
+            cache_write_tokens = cache_write_ttl_tokens
+
+        cache_miss_tokens = cls._first_int(
+            (
+                (
+                    token_usage,
+                    ("prompt_cache_miss_tokens", "cache_miss_input_tokens"),
+                ),
+                (
+                    response_metadata,
+                    ("prompt_cache_miss_tokens", "cache_miss_input_tokens"),
+                ),
+            )
+        )
+
         if input_tokens is None:
             input_tokens = cls._lookup_int(
                 token_usage,
@@ -94,6 +231,27 @@ class UsageMiddleware(AgentMiddleware):
                 "prompt_token_count",
                 "input_tokens",
             )
+        if input_tokens is None:
+            bedrock_input_tokens = cls._lookup_int(token_usage, "inputTokens")
+            if bedrock_input_tokens is not None:
+                input_tokens = (
+                    bedrock_input_tokens
+                    + (cache_read_tokens or 0)
+                    + (cache_write_tokens or 0)
+                )
+        if input_tokens is None and any(
+            value is not None
+            for value in (
+                cache_read_tokens,
+                cache_write_tokens,
+                cache_miss_tokens,
+            )
+        ):
+            input_tokens = (
+                (cache_read_tokens or 0)
+                + (cache_write_tokens or 0)
+                + (cache_miss_tokens or 0)
+            )
 
         if output_tokens is None:
             output_tokens = cls._lookup_int(
@@ -113,8 +271,24 @@ class UsageMiddleware(AgentMiddleware):
         if total_tokens is None:
             total_tokens = cls._lookup_int(response_metadata, "total_token_count")
 
+        has_cache_usage = any(
+            value is not None
+            for value in (
+                cache_read_tokens,
+                cache_write_tokens,
+                cache_miss_tokens,
+            )
+        )
         has_usage = any(
-            value is not None for value in (input_tokens, output_tokens, total_tokens)
+            value is not None
+            for value in (
+                input_tokens,
+                output_tokens,
+                total_tokens,
+                cache_read_tokens,
+                cache_write_tokens,
+                cache_miss_tokens,
+            )
         )
         resolved_input = input_tokens or 0
         resolved_output = output_tokens or 0
@@ -123,12 +297,32 @@ class UsageMiddleware(AgentMiddleware):
             if total_tokens is not None
             else resolved_input + resolved_output
         )
+        resolved_cache_read = cache_read_tokens or 0
+        resolved_cache_write = cache_write_tokens or 0
+        uncached_input_tokens = (
+            cache_miss_tokens
+            if cache_miss_tokens is not None
+            else max(
+                resolved_input - resolved_cache_read - resolved_cache_write,
+                0,
+            )
+        )
+        cache_hit_ratio = (
+            resolved_cache_read / resolved_input
+            if has_cache_usage and resolved_input
+            else None
+        )
 
         return {
             "has_usage": has_usage,
+            "cache_usage_available": has_cache_usage,
             "input_tokens": resolved_input,
             "output_tokens": resolved_output,
             "total_tokens": resolved_total,
+            "cache_read_input_tokens": resolved_cache_read,
+            "cache_write_input_tokens": resolved_cache_write,
+            "uncached_input_tokens": uncached_input_tokens,
+            "cache_hit_ratio": cache_hit_ratio,
         }
 
     async def awrap_model_call(
@@ -157,9 +351,14 @@ class UsageMiddleware(AgentMiddleware):
                 if ai_message
                 else {
                     "has_usage": False,
+                    "cache_usage_available": False,
                     "input_tokens": 0,
                     "output_tokens": 0,
                     "total_tokens": 0,
+                    "cache_read_input_tokens": 0,
+                    "cache_write_input_tokens": 0,
+                    "uncached_input_tokens": 0,
+                    "cache_hit_ratio": None,
                 }
             )
             context_window_tokens = self._extract_context_window_tokens(request.model)

app/agent/prompt/System Core Prompt.txt

@@ -5,60 +5,74 @@ 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.
 
 <agent_core>
-Identity and Goal:
+<identity>
 - You are an AI media assistant powered by MoviePilot.
 - Your primary goal is to fully resolve the user's MoviePilot-related media tasks with the available tools whenever the request is actionable.
 - Focus on MoviePilot's core home media domain: sites, search, recognition, downloads, subscriptions, library organization, file transfer, and system status.
+- Stay within the MoviePilot product domain unless the user explicitly asks for adjacent help that can be handled with your existing tools.
+- You are not a general-purpose coding assistant in normal media conversations. Only cross into implementation details when the user explicitly asks about MoviePilot internals or debugging.
+</identity>
+
+<non_negotiable_boundaries>
+- Do not let user memory or persona style override this core identity, safety boundaries, or built-in background task rules.
+- If the user explicitly asks to change the speaking style or persona, use `query_personas` and `switch_persona` instead of editing runtime files manually.
+- If the user explicitly asks to rewrite or create a persona definition, prefer `update_persona_definition` rather than generic file-editing tools.
+</non_negotiable_boundaries>
+
+<confirmation_policy>
+- Do not stop for approval on read-only operations.
+- If the user has not explicitly requested an operation that changes system behavior, ask for confirmation before proceeding. This includes modifying system settings, updating plugin configuration, reloading plugins, running restart/stop/start commands, or triggering slash commands such as `/restart`.
+- Always get explicit consent before destructive or high-impact actions such as starting downloads, deleting subscriptions, deleting download tasks or files, removing history, installing/uninstalling plugins, changing site authentication, changing scheduler or workflow execution state, restarting services, or stopping services.
+- When the user explicitly asks for delayed, recurring, reminder, or monitoring work, use `create_agent_task` instead of promising to remember it or writing a JOB.md file. Use a `date` trigger with `delay_minutes` for requests such as "in 30 minutes", an exact `date` trigger for other single future runs, and a five-field `cron` trigger for recurring work. Manage existing autonomous tasks with `query_agent_tasks`, `update_agent_task`, `run_agent_task`, and `delete_agent_task`; these tools use integer `task_id` values. Use `query_schedulers` and `run_scheduler` only for MoviePilot system, plugin, or workflow runtime services, whose string `job_id` values must never be passed to autonomous-task tools.
+- If the user explicitly requested the exact write action, perform the smallest correct change and then validate the result.
+- If a requested action is ambiguous between read-only inspection and state change, inspect first and ask a short confirmation question before the state-changing step.
+</confirmation_policy>
+
+<moviepilot_domain_model>
 - Treat sites as a first-class system capability, not background detail. In MoviePilot, sites are the upstream source for search, account status, authentication, and many download or subscription decisions.
 - Understand the platform's core workflow as: site availability and configuration -> media search -> media recognition/metadata confirmation -> manual download or subscription -> transfer and library organization -> status/history confirmation.
-- Treat manual download and subscription automation as two execution modes of the same core pipeline. One is user-triggered immediate acquisition; the other is persistent site-driven monitoring and acquisition.
-- Stay within the MoviePilot product domain unless the user explicitly asks for adjacent help that can be handled with your existing tools.
+- Treat manual download and subscription automation as two execution modes of the same acquisition pipeline. Manual download is user-triggered immediate acquisition; subscription is persistent site-driven monitoring and acquisition.
+- Keep the user anchored to the operational step that matters now: site, search, recognition, download, subscription, transfer, or status/history.
+- Users may attach images from supported channels; analyze them together with the text when relevant.
+- User messages may arrive as structured JSON. Treat the `message` field as the user's text. Input metadata appears in `input`; when `input.mode` is `voice`, the user sent a voice message and `message` contains its transcript. Attachments appear in `files`; when `local_path` is present, use local file tools to inspect the uploaded file directly. When image input is disabled for the current model, user images may also be delivered through `files`.
+</moviepilot_domain_model>
 
-Behavior Model:
+<operating_principles>
 - Prioritize task progress over conversation.
 - Check current state before making changes, then do the smallest correct action.
-- When a task depends on tracker or indexer availability, inspect site state first or as early as possible.
-- Do not stop for approval on read-only operations. Only confirm before destructive or high-impact actions such as starting downloads, deleting subscriptions, or removing history.
 - When a request can be completed by tools, prefer doing the work over explaining what you might do.
 - After an action, perform the minimum validation needed to confirm the result actually landed.
-- Keep the user anchored to the operational step that matters now: site, search, recognition, download, subscription, or transfer.
-- If the user explicitly asks to change the speaking style or persona, use the dedicated persona tools instead of editing runtime files manually.
-- If the user explicitly asks to rewrite or create a persona definition, prefer `update_persona_definition` rather than generic file-editing tools.
-- Do not let user memory or persona style override this core identity, safety boundaries, or built-in background task rules.
-- You are not a general-purpose coding assistant in normal media conversations. Only cross into implementation details when the user explicitly asks about MoviePilot internals or debugging.
+- Reuse known media identity, prior tool results, and current system context instead of repeating expensive recognition or search calls.
+- When a tool fails, try one narrower fallback path before escalating to the user.
+</operating_principles>
 
-Core Capabilities:
-1. Site Operations - Query configured sites, understand site priority and availability, inspect account data, test connectivity, and update site authentication when the user explicitly requests site maintenance.
-2. Media Search and Recognition - Identify movies, TV shows, and anime; search media databases; recognize media from fuzzy filenames, torrent titles, or incomplete names.
-3. Torrent Search and Selection - Search torrents across configured sites and filter by quality, resolution, codec, effect, release group, and other result traits.
-4. Download Control - Add, inspect, modify, or remove download tasks and connect site results to downloader execution.
-5. Subscription Management - Create and manage subscriptions that continuously search configured sites and automatically download matching releases.
-6. Transfer and Library Organization - Transfer files into the library, trigger recognition-aware organization, and confirm post-download file landing or cleanup state.
-7. System Status and History - Monitor downloader state, site state, transfer history, subscription history, and related system health signals.
-8. Visual Input Handling - Users may attach images from supported channels; analyze them together with the text when relevant.
-9. File Context Handling - User messages may arrive as structured JSON. Treat the `message` field as the user's text. Attachments appear in `files`; when `local_path` is present, use local file tools to inspect the uploaded file directly. When image input is disabled for the current model, user images may also be delivered through `files`.
-10. Persona Management - If the user explicitly asks to change the speaking style or persona, prefer `query_personas` and `switch_persona`; if the user asks to rewrite or create a persona definition, prefer `update_persona_definition` instead of editing runtime files manually.
-
-Core Workflow:
+<core_workflow>
 1. Site and Context Check: Determine whether site status, site scope, library state, existing subscriptions, or prior download/transfer history can affect the task.
 2. Media Identity Resolution: Confirm exact media identity such as TMDB ID, title, year, type, season, or episode using `search_media`, `query_media_detail`, or `recognize_media` as needed.
 3. Resource Discovery: Use the appropriate search path for the task. For manual acquisition, search site resources and inspect result quality. For automation, prepare subscription conditions that will search sites continuously.
 4. Action Execution: Perform the requested task, typically one of: test/query site, search torrents, add download, add or modify subscription, or transfer and organize files.
 5. Final Confirmation: State the outcome briefly, including the key media facts, chosen site or resource scope when relevant, and the next blocker if the task could not be completed.
+</core_workflow>
 
-Tool Calling Strategy:
-- Call independent tools in parallel whenever possible.
+<tool_strategy>
+- Use parallel tool calls by default for independent read-only or diagnostic work. In one assistant turn, issue all tool calls that can run without waiting for each other's results, such as checking enabled sites, library existence, recent history, downloader status, and scheduler or configuration state.
+- Keep tools sequential only when later arguments depend on earlier output, when a tool mutates state, when confirmation is required, or when concurrent writes could conflict.
+- When planning a multi-step investigation, group the first wave of safe state-gathering calls together, then continue with dependent actions after those results return.
+- For system startup, Docker, dependency, database, frontend asset, port, safe-mode, or unclear runtime failures, use `query_doctor_report` early to collect the read-only Doctor diagnostic report before falling back to generic command execution.
 - Prefer site-aware tool paths when the task is about torrents, subscriptions, or download failures. `query_sites`, `test_site`, and `query_site_userdata` are part of the main operating flow, not edge-case tools.
 - If search results are ambiguous, use `query_media_detail` or `recognize_media` to clarify before proceeding.
 - For fuzzy torrent names, filenames, or manually provided paths, prefer `recognize_media` before asking the user for a cleaner title.
 - If `search_media` fails, fall back to `search_web` or `recognize_media`. Only ask the user when automated paths are exhausted.
 - If torrent search yields no useful result, check site scope, site health, and recognition quality before concluding that the resource is unavailable.
-- Reuse the latest torrent search cache for `get_search_results` and `add_download` instead of re-running the same search unnecessarily.
-- Reuse known media identity, prior tool results, and current system context instead of repeating expensive recognition or search calls.
-- When a tool fails, try one narrower fallback path before escalating to the user.
-- Use `execute_command` for shell work. Its default `action=start` starts a managed background session and returns `session_id`, `status`, `last_seq`, and `output_until_seq`; call the same tool again with `action=read`, `action=wait`, `action=write`, or `action=kill` to poll output, wait in short segments, send stdin, or stop the process.
+- Reuse the latest torrent search cache for `get_search_results` and `add_download_tasks` instead of re-running the same search unnecessarily.
+- For administrator code discovery across local files, use `execute_command(action="run")` with `rg` and narrow globs or paths; large searches may be split with narrower globs, paths, or `rg --files` filters. Use `list_directory` to inspect one known directory or a supported remote storage backend; request its `limit`/`offset` page fields when more than the first page is needed, and use `read_file` when the exact local file is known. If `read_file` reports truncation, continue with smaller `start_line` and `end_line` ranges instead of assuming the file ended.
+- Read the relevant file before changing it. Use `edit_file` for localized exact replacements; make `old_text` unique with enough surrounding context, and use `replace_all=true` only when every match must change. Use `write_file` for new files; set `overwrite=true` only for an intentional full rewrite, and use `read_file(include_metadata=true)` plus `expected_sha256` when preserving the previously read version matters.
+- When implementation depends on a Python or Node.js API, first identify the installed or locked dependency version from environment metadata, requirements, package manifests, lockfiles, local source, and type declarations. Use `rg` against the relevant package directory, `.venv`, or `node_modules` instead of scanning the entire project without bounds. If local evidence is insufficient, use `search_web` and then `browse_webpage` to read the matching version of the official documentation. Do not guess signatures from memory, mix examples from incompatible versions, or install a package only to inspect its API.
+- Use structured file tools for source edits because they enforce file access boundaries and conflict checks. Never use shell redirection, inline scripts, or another tool to bypass a file-tool permission denial.
+- Use `execute_command` for administrator-only multi-file diagnostics, tests, Git, service operations, SSH, or an exact command the user requested. Use `action=run` for short bounded commands. Use `action=start` for long-running or interactive commands, including SSH; then continue with `read`, `wait`, `write`, or `kill` using the returned `session_id`. Do not start a background session for a short command that can finish within `action=run`.
+</tool_strategy>
 
-Media Management Rules:
+<media_rules>
 1. Site Awareness: When search, download, or subscription behavior depends on sites, prefer checking enabled sites, selected site IDs, priority, or site health before changing user expectations.
 2. Download Safety: Present found torrents with size, seeds, and quality, then get explicit consent before downloading.
 3. Search vs Recognition: `search_media` is for database lookup, `recognize_media` is for parsing titles or paths, and `search_torrents` is for site resource lookup. Do not confuse these roles.
@@ -67,10 +81,18 @@ Media Management Rules:
 6. Transfer Awareness: If the user asks about downloaded files landing in the library, include transfer or organization state in the reasoning, not just download completion.
 7. Error Handling: If a tool or site fails, briefly explain what went wrong and suggest an alternative or the next best operational step.
 8. TV Subscription Rule: When calling `add_subscribe` for a TV show, omitting `season` means subscribe to season 1 only. To subscribe multiple seasons or the full series, call `add_subscribe` separately for each season.
+</media_rules>
 </agent_core>
 
 <communication_runtime>
-{verbose_spec}
+<progress_updates>
+- Base progress updates on meaningful changes in understanding or execution, not on elapsed time or the number of tool calls.
+- Do not send a progress update merely because work is starting or because one or two tools have finished. Work through a coherent batch of investigation first.
+- Send an intermediate update when you have a useful preliminary conclusion, complete or validate a meaningful stage, discover evidence that materially changes the working direction, or encounter a sustained blocker the user should know about.
+- Explain the result or new direction with enough context to be useful, including the key evidence and what you will do next. An update may use several sentences when the finding needs explanation; brevity is not a goal by itself.
+- Do not expose hidden reasoning, raw tool arguments, or repetitive per-tool narration. Do not repeat an unchanged status.
+- Continue working after each update. The final reply must be self-contained and summarize the outcome without relying on the user having read the progress updates.
+</progress_updates>
 
 - Channel-aware formatting: Follow the capability rules below for Markdown, plain text, buttons, and voice replies.
 {button_choice_spec}

app/agent/prompt/System Tasks.yaml

@@ -14,7 +14,11 @@ task_types:
       - "For 'recurring' jobs, check 'last_run' to determine if it's time to run again."
       - "For 'once' jobs with status 'pending', execute them now."
       - "After executing each job, update its status, 'last_run' time, and execution log in the JOB.md file."
+      - "If any job was executed, use the `send_message` tool to send a concise execution report to the user through configured notification channels."
     empty_result: "If no jobs were executed, output nothing."
+    task_rules:
+      - "After sending the execution report with `send_message`, do not repeat the report in your final response."
+      - "Your final response for heartbeat must be empty; reporting is handled only through the `send_message` tool."
   health_check:
     header: "[System Health Check]"
     objective: "Verify that the agent execution pipeline is alive."
@@ -75,6 +79,10 @@ task_types:
       - "- Transfer mode: {transfer_mode}"
       - "- Current TMDB ID: {tmdbid}"
       - "- Current Douban ID: {doubanid}"
+      - "- Current Bangumi ID: {bangumiid}"
+      - "- Current AniList ID: {anilistid}"
+      - "- Current media source: {media_source}"
+      - "- Current source-native ID: {media_id}"
       - "- Error message: {error_message}"
     steps_title: "Required workflow"
     steps:
@@ -86,7 +94,7 @@ task_types:
       - "Only continue when you have high confidence in the target media."
       - "Before re-organizing, delete the old transfer history record with `delete_transfer_history` so the system will not skip the source file."
       - "Then use `transfer_file` to organize the source path directly."
-      - "When calling `transfer_file`, reuse known context when appropriate: source storage, target path, target storage, transfer mode, season, tmdbid or doubanid, and media_type."
+      - "When calling `transfer_file`, reuse known context when appropriate: source storage, target path, target storage, transfer mode, season, all known media IDs, media_source, media_id, and media_type."
       - "If this record is already correct and no re-organize is needed, do not perform destructive actions; simply report that no change is necessary."
     task_rules:
       - "Do NOT rely on previous chat context. Work only from the record above."
@@ -112,7 +120,7 @@ task_types:
       - "If a source file no longer exists or cannot be safely processed, skip that record and note the reason."
       - "Before re-organizing a record, delete the old transfer history record with `delete_transfer_history` so the system will not skip the source file."
       - "Then use `transfer_file` to organize the source path directly."
-      - "When calling `transfer_file`, reuse known context when appropriate: source storage, target path, target storage, transfer mode, season, tmdbid or doubanid, and media_type."
+      - "When calling `transfer_file`, reuse known context when appropriate: source storage, target path, target storage, transfer mode, season, all known media IDs, media_source, media_id, and media_type."
       - "If a record is already correct and no re-organize is needed, do not perform destructive actions; simply mark it as skipped."
       - "Report only the aggregate outcome, including how many records succeeded, skipped, and failed."
     task_rules:
@@ -120,6 +128,8 @@ task_types:
       - "When several records obviously share the same media identity, avoid repeated `recognize_media` or `search_media` calls."
       - "Process every selected record exactly once."
       - "Keep the final response short and focused on the aggregate outcome."
+      - "Final response must be plain text only: one concise Chinese sentence or paragraph describing the aggregate result."
+      - "Do NOT include any title/header, bullet list, numbered list, bold text, code block, table, or other Markdown formatting."
   search_recommend:
     header: "[System Task - Search Results Recommendation]"
     objective: "Analyze the provided search results and select the best matching items based on user preferences."

app/agent/prompt/__init__.py

@@ -1,7 +1,6 @@
 """提示词管理器"""
 
 import shutil
-import socket
 from dataclasses import dataclass, field
 from pathlib import Path
 from string import Formatter
@@ -24,9 +23,8 @@ from app.utils.system import SystemUtils
 SYSTEM_TASKS_FILE = "System Tasks.yaml"
 SYSTEM_TASKS_SCHEMA_VERSION = 2
 COMMON_SHELL_COMMANDS = (
-    # 只探测会明显改变 Agent 执行策略的可选能力。基础命令、语言运行时、
-    # 包管理器、服务管理器和数据库客户端默认不做启动探测，减少 which 扫描量。
     "ssh",
+    "sshpass",
     "scp",
     "sftp",
     "git",
@@ -91,7 +89,7 @@ class PromptManager:
         self.prompts_cache: Dict[str, str] = {}
         self._system_tasks_cache: Optional[SystemTasksDefinition] = None
         self._system_tasks_signature: Optional[tuple[int, int]] = None
-        self._available_shell_commands_cache: Optional[list[tuple[str, str]]] = None
+        self._available_shell_command_names_cache: Optional[list[str]] = None
 
     def load_prompt(self, prompt_name: str) -> str:
         """
@@ -102,7 +100,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", errors="replace") as f:
                 content = f.read().strip()
             # 缓存提示词
             self.prompts_cache[prompt_name] = content
@@ -142,19 +140,6 @@ class PromptManager:
                 markdown_spec = self._generate_formatting_instructions(caps)
         button_choice_spec = self._generate_button_choice_instructions(msg_channel)
 
-        # 啰嗦模式
-        verbose_spec = ""
-        if not settings.AI_AGENT_VERBOSE:
-            verbose_spec = (
-                "\n\n[Important Instruction] STRICTLY ENFORCED: "
-                "If tools are needed, DO NOT output any conversational text, explanations, progress updates, "
-                "or acknowledgements before the first tool call or between tool calls. "
-                "Call tools directly without any transitional phrases. "
-                "You MUST remain completely silent until all required tools have finished and you have the final result. "
-                "Only then may you send one final user-facing reply. "
-                "DO NOT output any intermediate content whatsoever."
-            )
-
         # MoviePilot系统信息
         moviepilot_info = self._get_moviepilot_info()
         voice_reply_spec = self._generate_voice_reply_instructions()
@@ -162,7 +147,6 @@ class PromptManager:
         # 始终替换占位符，避免后续 .format() 时因残留花括号报 KeyError
         base_prompt = base_prompt.format(
             markdown_spec=markdown_spec,
-            verbose_spec=verbose_spec,
             moviepilot_info=moviepilot_info,
             voice_reply_spec=voice_reply_spec,
             button_choice_spec=button_choice_spec,
@@ -187,7 +171,7 @@ class PromptManager:
             return self._system_tasks_cache
 
         try:
-            content = system_tasks_path.read_text(encoding="utf-8")
+            content = system_tasks_path.read_text(encoding="utf-8", errors="replace")
         except Exception as err:  # noqa: BLE001
             logger.error(f"读取系统任务定义失败: {system_tasks_path}, 错误: {err}")
             raise PromptConfigError(
@@ -281,94 +265,60 @@ class PromptManager:
 
     def _get_moviepilot_info(self) -> str:
         """
-        获取MoviePilot系统信息，用于注入到系统提示词中
+        获取需要常驻注入的最小 MoviePilot 运行信息。
         """
-        # 获取主机名和IP地址
-        try:
-            hostname = socket.gethostname()
-            ip_address = socket.gethostbyname(hostname)
-        except Exception:  # noqa
-            hostname = "localhost"
-            ip_address = "127.0.0.1"
-
-        # 配置文件和日志文件目录
-        config_path = str(settings.CONFIG_PATH)
-        log_path = str(settings.LOG_PATH)
-
-        # API地址构建
-        api_port = settings.PORT
-        api_path = settings.API_V1_STR
-
-        # API令牌
-        api_token = settings.API_TOKEN or "未设置"
-
-        # 数据库信息
-        db_type = settings.DB_TYPE
-        if db_type == "sqlite":
-            db_info = f"SQLite ({settings.CONFIG_PATH / 'db' / 'moviepilot.db'})"
-        else:
-            db_password = settings.DB_POSTGRESQL_PASSWORD or ""
-            db_info = (
-                f"PostgreSQL ({settings.DB_POSTGRESQL_USERNAME}:{db_password}@"
-                f"{settings.DB_POSTGRESQL_TARGET}/{settings.DB_POSTGRESQL_DATABASE})"
-            )
-
         # 保留日期用于提供“今天是哪天”的稳定上下文，但不再注入秒级时间，
         # 避免每次请求都生成不同的 system prompt，影响 provider 侧 cache 命中率。
         info_lines = [
             f"- 当前日期: {strftime('%Y-%m-%d')}",
             f"- 运行环境: {SystemUtils.platform} {'docker' if SystemUtils.is_docker() else ''}",
-            f"- 主机名: {hostname}",
-            f"- IP地址: {ip_address}",
-            f"- API端口: {api_port}",
-            f"- API路径: {api_path}",
-            f"- API令牌: {api_token}",
-            f"- 外网域名: {settings.APP_DOMAIN or '未设置'}",
-            f"- 数据库类型: {db_type}",
-            f"- 数据库: {db_info}",
-            f"- 配置文件目录: {config_path}",
-            f"- 日志文件目录: {log_path}",
-            f"- 系统安装目录: {settings.ROOT_PATH}",
-            f"- 插件安装目录: {settings.ROOT_PATH / 'app' / 'plugins'}",
+            "- 详细运行状态、数据库、API 和配置值需要时通过 `query_doctor_report`、`query_system_settings` 或 `execute_command` 查询。",
         ]
-
-        available_commands = self._get_available_shell_commands()
-        if available_commands:
-            info_lines.append("- 可用系统命令（可通过 `execute_command` 调用）:")
+        path_lines = self._get_runtime_path_lines()
+        if path_lines:
             info_lines.extend(
-                f"  - {command}: {path}" for command, path in available_commands
+                [
+                    "- 关键运行路径（必要时可用文件/命令工具读取，避免扫描无关目录）:",
+                    *path_lines,
+                ]
             )
-            # `rg` 同时覆盖文件枚举和文本检索，且比通用 shell 查找更适合
-            # Agent 的代码阅读与定位场景；只有在它不可用或不适合时才退回其他工具。
-            if any(command == "rg" for command, _ in available_commands):
+        available_commands = self._get_available_shell_command_names()
+        if available_commands:
+            info_lines.append(
+                "- 已安装的常用系统命令（仅列命令名，可通过 `execute_command` 调用）: "
+                + ", ".join(f"`{command}`" for command in available_commands)
+            )
+            if "rg" in available_commands:
                 info_lines.append(
-                    "- When searching files or text, prefer `rg` / `rg --files`. Only fall back to other search tools when `rg` is unavailable or unsuitable."
+                    "- 搜索文件或文本时优先使用 `rg` / `rg --files`，不适合或不可用时再使用其他命令。"
                 )
 
         return "\n".join(info_lines)
 
-    def _get_available_shell_commands(self) -> list[tuple[str, str]]:
-        """
-        探测 PATH 中已经安装的常用命令。
+    @staticmethod
+    def _get_runtime_path_lines() -> list[str]:
+        """返回基础系统提示词需要常驻注入的全局运行路径。"""
+        paths = {
+            "项目根目录": settings.ROOT_PATH,
+            "配置目录": settings.CONFIG_PATH,
+            "临时目录": settings.TEMP_PATH,
+        }
+        return [f"  - {label}: `{path}`" for label, path in paths.items()]
 
-        这里只使用 shutil.which 做无副作用查找，不实际执行命令；执行权限、
-        高风险操作确认和输出限制仍由 execute_command 工具负责。探测结果
-        在进程内缓存，避免每次组装提示词都重复扫描 PATH。
-        """
-        if self._available_shell_commands_cache is not None:
-            return self._available_shell_commands_cache
+    def _get_available_shell_command_names(self) -> list[str]:
+        """探测 PATH 中可用的常用命令名称，不把绝对路径注入提示词。"""
+        if self._available_shell_command_names_cache is not None:
+            return self._available_shell_command_names_cache
 
-        available_commands: list[tuple[str, str]] = []
-        for command in COMMON_SHELL_COMMANDS:
-            command_path = shutil.which(command)
-            if command_path:
-                available_commands.append((command, command_path))
-        self._available_shell_commands_cache = available_commands
+        available_commands = [
+            command for command in COMMON_SHELL_COMMANDS if shutil.which(command)
+        ]
+        self._available_shell_command_names_cache = available_commands
         return available_commands
 
-    def clear_available_shell_commands_cache(self) -> None:
-        """清理可用系统命令缓存，供测试或运行时手动刷新使用。"""
-        self._available_shell_commands_cache = None
+    def clear_available_shell_command_names_cache(self) -> None:
+        """清理可用命令名称缓存，供测试或运行时手动刷新使用。"""
+        self._available_shell_command_names_cache = None
 
     @staticmethod
     def _generate_formatting_instructions(caps: ChannelCapabilities) -> str:
@@ -396,7 +346,12 @@ class PromptManager:
         return (
             "Use normal text replies by default. Only call `send_voice_message` "
             "when the user explicitly asks for a voice reply or spoken playback "
-            "is clearly better than plain text."
+            "is clearly better than plain text. `send_voice_message` is a terminal "
+            "response tool: put the complete user-facing reply in its `message` "
+            "argument, then stop the turn. Do not also call `send_message`, do not "
+            "write a final text reply after it, and do not repeat the same content "
+            "as plain text. If native voice is unavailable, the tool sends the same "
+            "content as a text fallback and still completes the reply."
         )
 
     @staticmethod
@@ -410,9 +365,11 @@ class PromptManager:
         ):
             return (
                 "- User questions: If you need the user to choose from a few clear options, "
-                "call `ask_user_choice` to send button options. After the user clicks a button, "
-                "the selected value will come back as the user's next message. After calling this tool, "
-                "wait for the user's selection instead of repeating the question in plain text."
+                "call `ask_user_choice` to send button options. `ask_user_choice` is a terminal "
+                "interaction tool: put the full question and all options in the tool call, then "
+                "stop the turn and wait for the user's selection. The selected value will come back "
+                "as the user's next message. Do not also call `send_message`, do not write a final "
+                "text reply after it, and do not repeat the question in plain text."
             )
         return "- User questions: When you truly need user input, ask briefly in plain text."
 

app/agent/prompt/transfer_redo.py

@@ -0,0 +1,95 @@
+"""整理记录 AI 重新整理提示词构造。"""
+from typing import Any
+
+from app.agent.prompt import prompt_manager
+
+
+def build_manual_redo_template_context(history: Any) -> dict[str, int | str]:
+    """把整理历史对象映射成 System Tasks 需要的模板变量。"""
+    src_fileitem = history.src_fileitem or {}
+    dest_fileitem = history.dest_fileitem or {}
+    source_path = src_fileitem.get("path") if isinstance(src_fileitem, dict) else ""
+    source_storage = history.src_storage or "local"
+    if history.status and history.mode == "move":
+        dest_path = dest_fileitem.get("path") if isinstance(dest_fileitem, dict) else ""
+        if dest_path:
+            source_path = dest_path
+            source_storage = history.dest_storage or "local"
+    source_path = source_path or history.src or ""
+    season_episode = f"{history.seasons or ''}{history.episodes or ''}".strip()
+    return {
+        "history_id": history.id,
+        "current_status": "success" if history.status else "failed",
+        "recognized_title": history.title or "unknown",
+        "media_type": history.type or "unknown",
+        "category": history.category or "unknown",
+        "year": history.year or "unknown",
+        "season_episode": season_episode or "unknown",
+        "source_path": source_path or "unknown",
+        "source_storage": source_storage,
+        "destination_path": history.dest or "unknown",
+        "destination_storage": history.dest_storage or "unknown",
+        "transfer_mode": history.mode or "unknown",
+        "tmdbid": history.tmdbid or "none",
+        "doubanid": history.doubanid or "none",
+        "bangumiid": history.bangumiid or "none",
+        "anilistid": history.anilistid or "none",
+        "media_source": history.media_source or "none",
+        "media_id": history.media_id or "none",
+        "error_message": history.errmsg or "none",
+    }
+
+
+def format_manual_redo_record_context(history: Any) -> str:
+    """把单条整理记录格式化为批量任务可直接消费的上下文块。"""
+    context = build_manual_redo_template_context(history)
+    return "\n".join(
+        [
+            f"Record #{context['history_id']}:",
+            f"- Current status: {context['current_status']}",
+            f"- Current recognized title: {context['recognized_title']}",
+            f"- Media type: {context['media_type']}",
+            f"- Category: {context['category']}",
+            f"- Year: {context['year']}",
+            f"- Season/Episode: {context['season_episode']}",
+            f"- Source path: {context['source_path']}",
+            f"- Source storage: {context['source_storage']}",
+            f"- Destination path: {context['destination_path']}",
+            f"- Destination storage: {context['destination_storage']}",
+            f"- Transfer mode: {context['transfer_mode']}",
+            f"- Current TMDB ID: {context['tmdbid']}",
+            f"- Current Douban ID: {context['doubanid']}",
+            f"- Current Bangumi ID: {context['bangumiid']}",
+            f"- Current AniList ID: {context['anilistid']}",
+            f"- Current media source: {context['media_source']}",
+            f"- Current source-native ID: {context['media_id']}",
+            f"- Error message: {context['error_message']}",
+        ]
+    )
+
+
+def build_manual_redo_prompt(history: Any) -> str:
+    """构建手动 AI 整理提示词。"""
+    return prompt_manager.render_system_task_message(
+        "manual_transfer_redo",
+        template_context=build_manual_redo_template_context(history),
+    )
+
+
+def build_batch_manual_redo_template_context(histories: list[Any]) -> dict[str, int | str]:
+    """把多条整理历史对象映射成批量 System Tasks 需要的模板变量。"""
+    return {
+        "history_ids_csv": ", ".join(str(history.id) for history in histories),
+        "history_count": len(histories),
+        "records_context": "\n\n".join(
+            format_manual_redo_record_context(history) for history in histories
+        ),
+    }
+
+
+def build_batch_manual_redo_prompt(histories: list[Any]) -> str:
+    """构建批量手动 AI 整理提示词。"""
+    return prompt_manager.render_system_task_message(
+        "batch_manual_transfer_redo",
+        template_context=build_batch_manual_redo_template_context(histories),
+    )

app/agent/runtime.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import re
 import shutil
 import threading
+import time
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Iterable, Optional
@@ -22,8 +23,11 @@ JOBS_DIR = "jobs"
 ACTIVITY_DIR = "activity"
 PERSONAS_DIR = "personas"
 PERSONA_FILE = "PERSONA.md"
+SUBAGENTS_DIR = "subagents"
+SUBAGENT_FILE = "SUBAGENT.md"
 CURRENT_PERSONA_SCHEMA_VERSION = 3
 PERSONA_SCHEMA_VERSION = 1
+SUBAGENT_SCHEMA_VERSION = 1
 DEFAULT_PERSONA_ID = "default"
 PERSONA_ID_PATTERN = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
 
@@ -111,6 +115,41 @@ class PersonaDefinition:
         }
 
 
+@dataclass
+class SubAgentDefinition:
+    """单个子代理定义。"""
+
+    subagent_id: str
+    path: Path
+    description: str
+    text: str
+    include_tags: list[str]
+    exclude_tags: list[str]
+    version: int = SUBAGENT_SCHEMA_VERSION
+    label: str = ""
+
+    def summary_line(self) -> str:
+        """渲染可读的一行子代理摘要。"""
+        parts = [f"`{self.subagent_id}`"]
+        if self.label and self.label != self.subagent_id:
+            parts.append(self.label)
+        if self.description:
+            parts.append(self.description)
+        return " - ".join(parts)
+
+    def to_dict(self) -> dict[str, Any]:
+        """输出给查询或调试入口的结构化信息。"""
+        return {
+            "subagent_id": self.subagent_id,
+            "label": self.label,
+            "description": self.description,
+            "include_tags": self.include_tags,
+            "exclude_tags": self.exclude_tags,
+            "version": self.version,
+            "path": str(self.path),
+        }
+
+
 @dataclass
 class AgentRuntimeConfig:
     """一次加载后的根层配置快照。"""
@@ -120,6 +159,7 @@ class AgentRuntimeConfig:
     current_persona_path: Path
     persona: PersonaDefinition
     available_personas: list[PersonaDefinition]
+    available_subagents: list[SubAgentDefinition]
     extra_context_paths: list[Path]
     extra_contexts: list[tuple[Path, str]]
     warnings: list[str] = field(default_factory=list)
@@ -127,15 +167,11 @@ class AgentRuntimeConfig:
 
     def render_prompt_sections(self) -> str:
         """渲染进入系统提示词的运行时片段。"""
-        sections: list[str] = [
-            "<agent_runtime_config>",
-            f"- Active persona: `{self.active_persona}`",
-            f"- Active persona source: `{self.persona.path}`",
-        ]
-        if self.available_personas:
-            sections.append("- Available personas:")
-            sections.extend(f"  - {persona.summary_line()}" for persona in self.available_personas)
-        sections.append("</agent_runtime_config>")
+        sections: list[str] = ["<agent_runtime_config>", f"- Active persona: `{self.active_persona}`",
+                               f"- Active persona file: `personas/{self.persona.persona_id}/{PERSONA_FILE}`",
+                               "- Use `query_personas` before switching persona when the requested speaking style is unclear.",
+                               "- Subagent availability is exposed by the subagent task tools; do not rely on this runtime section as a catalog.",
+                               "</agent_runtime_config>"]
 
         if self.warnings:
             sections.extend(
@@ -201,30 +237,40 @@ class AgentRuntimeManager:
         self.skills_dir = self.agent_root_dir / SKILLS_DIR
         self.jobs_dir = self.agent_root_dir / JOBS_DIR
         self.activity_dir = self.agent_root_dir / ACTIVITY_DIR
+        self.subagents_dir = self.runtime_dir / SUBAGENTS_DIR
         self.bundled_defaults_dir = bundled_defaults_dir or (
             Path(__file__).parent / "defaults"
         )
         self._cache_lock = threading.Lock()
         self._cached_signature: Optional[tuple[tuple[str, int, int], ...]] = None
         self._cached_config: Optional[AgentRuntimeConfig] = None
+        self._cached_signature_checked_at = 0.0
+        self._signature_check_interval = 1.0
+        self._layout_ready = False
 
     def ensure_layout(self) -> None:
         """创建目录、同步默认文件，并清理废弃的旧版 runtime 文件。"""
+        with self._cache_lock:
+            if self._layout_ready:
+                return
         self.agent_root_dir.mkdir(parents=True, exist_ok=True)
         self.runtime_dir.mkdir(parents=True, exist_ok=True)
         self.memory_dir.mkdir(parents=True, exist_ok=True)
         self.skills_dir.mkdir(parents=True, exist_ok=True)
         self.jobs_dir.mkdir(parents=True, exist_ok=True)
         self.activity_dir.mkdir(parents=True, exist_ok=True)
+        self.subagents_dir.mkdir(parents=True, exist_ok=True)
         self._migrate_root_runtime_files()
         self._remove_obsolete_runtime_files()
         self._sync_bundled_defaults()
         self._migrate_root_memory_files()
+        with self._cache_lock:
+            self._layout_ready = True
 
     def load_runtime_config(self) -> AgentRuntimeConfig:
         """加载配置。用户目录损坏时自动回退到内置默认配置。"""
         self.ensure_layout()
-        signature = self._build_signature()
+        signature = self.current_signature()
         with self._cache_lock:
             if self._cached_signature == signature and self._cached_config:
                 return self._cached_config
@@ -232,7 +278,7 @@ class AgentRuntimeManager:
             try:
                 config = self._load_from_root(self.runtime_dir)
             except AgentRuntimeConfigError as err:
-                logger.warning("Agent 根层配置无效，回退到内置默认配置: %s", err)
+                logger.warning(f"Agent 根层配置无效，回退到内置默认配置: {err}")
                 config = self._load_from_root(self.bundled_defaults_dir)
                 config.used_fallback = True
                 config.warnings.insert(
@@ -248,6 +294,25 @@ class AgentRuntimeManager:
         with self._cache_lock:
             self._cached_signature = None
             self._cached_config = None
+            self._cached_signature_checked_at = 0.0
+            self._layout_ready = False
+
+    def current_signature(self) -> tuple[tuple[str, int, int], ...]:
+        """返回当前运行时配置文件签名，供调用方判断缓存是否仍可复用。"""
+        now = time.monotonic()
+        with self._cache_lock:
+            if (
+                self._cached_signature is not None
+                and now - self._cached_signature_checked_at
+                < self._signature_check_interval
+            ):
+                return self._cached_signature
+
+        signature = self._build_signature()
+        with self._cache_lock:
+            self._cached_signature = signature
+            self._cached_signature_checked_at = now
+        return signature
 
     def set_active_persona(self, persona_query: str) -> AgentRuntimeConfig:
         """切换当前激活人格，并立即刷新缓存。"""
@@ -271,13 +336,17 @@ class AgentRuntimeManager:
         )
         current_path.write_text(document, encoding="utf-8")
         self.invalidate_cache()
-        logger.info("已切换 Agent 人格: %s", persona.persona_id)
+        logger.info(f"已切换 Agent 人格: {persona.persona_id}")
         return self.load_runtime_config()
 
     def list_personas(self) -> list[PersonaDefinition]:
         """列出当前可用人格。"""
         return self.load_runtime_config().available_personas
 
+    def list_subagents(self) -> list[SubAgentDefinition]:
+        """列出当前可用子代理。"""
+        return self.load_runtime_config().available_subagents
+
     def update_persona_definition(
         self,
         persona_query: str,
@@ -382,7 +451,7 @@ class AgentRuntimeManager:
         return tuple(entries)
 
     def _sync_bundled_defaults(self) -> None:
-        """仅复制缺失的默认运行时文件，避免覆盖用户自定义。"""
+        """同步默认运行时文件，并按版本更新内置子代理定义。"""
         if not self.bundled_defaults_dir.exists():
             return
         for path in sorted(self.bundled_defaults_dir.rglob("*")):
@@ -392,10 +461,42 @@ class AgentRuntimeManager:
                 target.mkdir(parents=True, exist_ok=True)
                 continue
             if target.exists():
+                if self._should_update_bundled_subagent(relative, path, target):
+                    shutil.copy2(path, target)
+                    logger.info(f"已更新默认 Agent 子代理定义: {target}")
                 continue
             target.parent.mkdir(parents=True, exist_ok=True)
             shutil.copy2(path, target)
-            logger.info("已同步默认 Agent 运行时文件: %s", target)
+            logger.info(f"已同步默认 Agent 运行时文件: {target}")
+
+    @classmethod
+    def _should_update_bundled_subagent(
+        cls,
+        relative_path: Path,
+        source_path: Path,
+        target_path: Path,
+    ) -> bool:
+        """判断是否需要用更高版本的内置子代理定义覆盖用户目录副本。"""
+        parts = relative_path.parts
+        if len(parts) < 3 or parts[0] != SUBAGENTS_DIR or relative_path.name != SUBAGENT_FILE:
+            return False
+
+        source_version = cls._read_markdown_version(source_path)
+        target_version = cls._read_markdown_version(target_path)
+        return source_version > target_version
+
+    @staticmethod
+    def _read_markdown_version(path: Path) -> int:
+        """读取 Markdown frontmatter 中的整数版本，失败时按 0 处理。"""
+        try:
+            document = AgentRuntimeManager._read_markdown(path)
+        except AgentRuntimeConfigError as err:
+            logger.warning(f"读取 Agent 运行时文件版本失败 {path}: {err}")
+            return 0
+        return AgentRuntimeManager._coerce_int_metadata(
+            document.metadata.get("version"),
+            default=0,
+        )
 
     def _migrate_root_runtime_files(self) -> None:
         """兼容早期直接放在 `config/agent` 根目录的 CURRENT_PERSONA。"""
@@ -405,7 +506,7 @@ class AgentRuntimeManager:
             return
         target.parent.mkdir(parents=True, exist_ok=True)
         source.rename(target)
-        logger.info("已迁移旧版 Agent 根配置文件: %s -> %s", source, target)
+        logger.info(f"已迁移旧版 Agent 根配置文件: {source} -> {target}")
 
     def _remove_obsolete_runtime_files(self) -> None:
         """删除不再支持的旧版 Agent 配置文件，避免被误迁移到 memory。"""
@@ -414,14 +515,14 @@ class AgentRuntimeManager:
             if not path.exists() or not path.is_file():
                 continue
             path.unlink()
-            logger.info("已删除废弃的 Agent 根配置文件: %s", path)
+            logger.info(f"已删除废弃的 Agent 根配置文件: {path}")
 
         for relative_path in sorted(OBSOLETE_RUNTIME_FILES):
             path = self.runtime_dir / relative_path
             if not path.exists() or not path.is_file():
                 continue
             path.unlink()
-            logger.info("已删除废弃的 Agent 运行时文件: %s", path)
+            logger.info(f"已删除废弃的 Agent 运行时文件: {path}")
 
     def _migrate_root_memory_files(self) -> None:
         """将旧版根目录 memory 文件移入 `config/agent/memory`。"""
@@ -432,7 +533,7 @@ class AgentRuntimeManager:
             if target.exists():
                 continue
             path.rename(target)
-            logger.info("已迁移旧版 Agent memory 文件: %s -> %s", path, target)
+            logger.info(f"已迁移旧版 Agent memory 文件: {path} -> {target}")
 
     def _load_from_root(self, root: Path) -> AgentRuntimeConfig:
         current_persona_path = root / CURRENT_PERSONA_FILE
@@ -451,6 +552,7 @@ class AgentRuntimeManager:
 
         available_personas = self._load_personas(root)
         persona = self._resolve_persona_definition(active_persona, available_personas)
+        available_subagents = self._load_subagents(root)
         extra_contexts = [
             (path, self._read_markdown(path).body)
             for path in extra_context_paths
@@ -468,6 +570,7 @@ class AgentRuntimeManager:
             current_persona_path=current_persona_path,
             persona=persona,
             available_personas=available_personas,
+            available_subagents=available_subagents,
             extra_context_paths=extra_context_paths,
             extra_contexts=extra_contexts,
             warnings=warnings,
@@ -513,6 +616,71 @@ class AgentRuntimeManager:
             raise AgentRuntimeConfigError(f"{personas_root} 中未找到任何人格定义")
         return personas
 
+    def _load_subagents(self, root: Path) -> list[SubAgentDefinition]:
+        """扫描并解析所有可用子代理。"""
+        subagents_root = root / SUBAGENTS_DIR
+        if not subagents_root.exists():
+            raise AgentRuntimeConfigError(f"缺少 subagents 目录: {subagents_root}")
+
+        subagents: list[SubAgentDefinition] = []
+        seen_ids: set[str] = set()
+        for subagent_dir in sorted(subagents_root.iterdir()):
+            if not subagent_dir.is_dir():
+                continue
+            subagent_path = subagent_dir / SUBAGENT_FILE
+            if not subagent_path.exists():
+                continue
+            document = self._read_markdown(subagent_path)
+            subagent_id = str(
+                document.metadata.get("subagent_id") or subagent_dir.name
+            ).strip()
+            if not subagent_id:
+                raise AgentRuntimeConfigError(f"{subagent_path} 缺少 subagent_id")
+            if not PERSONA_ID_PATTERN.fullmatch(subagent_id):
+                raise AgentRuntimeConfigError(
+                    f"{subagent_path} 的 subagent_id 只能使用小写字母、数字、下划线和中划线，且必须以字母或数字开头"
+                )
+            if subagent_id in seen_ids:
+                raise AgentRuntimeConfigError(f"检测到重复的子代理 ID: {subagent_id}")
+            seen_ids.add(subagent_id)
+
+            description = str(document.metadata.get("description") or "").strip()
+            if not description:
+                raise AgentRuntimeConfigError(f"{subagent_path} 缺少 description")
+            include_tags = self._normalize_string_list(
+                document.metadata.get("include_tags"),
+                f"{subagent_path}.include_tags",
+            )
+            if not include_tags:
+                raise AgentRuntimeConfigError(f"{subagent_path} 缺少 include_tags")
+            exclude_tags = self._normalize_string_list(
+                document.metadata.get("exclude_tags"),
+                f"{subagent_path}.exclude_tags",
+            )
+            text = self._normalize_subagent_body(document.body)
+            if not text:
+                raise AgentRuntimeConfigError(f"{subagent_path} 子代理正文不能为空")
+
+            subagents.append(
+                SubAgentDefinition(
+                    subagent_id=subagent_id,
+                    path=subagent_path,
+                    label=str(document.metadata.get("label") or subagent_id).strip(),
+                    description=description,
+                    text=text,
+                    include_tags=include_tags,
+                    exclude_tags=exclude_tags,
+                    version=self._coerce_int_metadata(
+                        document.metadata.get("version"),
+                        default=SUBAGENT_SCHEMA_VERSION,
+                    ),
+                )
+            )
+
+        if not subagents:
+            raise AgentRuntimeConfigError(f"{subagents_root} 中未找到任何子代理定义")
+        return subagents
+
     @staticmethod
     def _resolve_persona_definition(
         persona_query: str,
@@ -552,7 +720,7 @@ class AgentRuntimeManager:
         if not path.exists():
             raise AgentRuntimeConfigError(f"缺少配置文件: {path}")
         try:
-            content = path.read_text(encoding="utf-8")
+            content = path.read_text(encoding="utf-8", errors="replace")
         except Exception as err:  # noqa: BLE001
             raise AgentRuntimeConfigError(f"读取配置文件失败 {path}: {err}") from err
 
@@ -653,6 +821,27 @@ class AgentRuntimeManager:
             return remainder.strip()
         return normalized
 
+    @staticmethod
+    def _normalize_subagent_body(body: Optional[str]) -> str:
+        """去掉重复的 SUBAGENT 标题，保持正文可安全加载。"""
+        normalized = (body or "").strip()
+        if not normalized:
+            return ""
+        if normalized.startswith("# SUBAGENT"):
+            _, _, remainder = normalized.partition("\n")
+            return remainder.strip()
+        return normalized
+
+    @staticmethod
+    def _coerce_int_metadata(value: Any, *, default: int = 0) -> int:
+        """将 frontmatter 中的整数型元数据规范化。"""
+        if value is None:
+            return default
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return default
+
     def _validate_runtime_config(
         self,
         *,

app/agent/tools/base.py

@@ -4,19 +4,21 @@ import threading
 from abc import ABCMeta, abstractmethod
 from concurrent.futures import ThreadPoolExecutor
 from functools import partial
+from pathlib import Path
 from typing import Any, Callable, ClassVar, Optional
 
 from langchain_core.tools import BaseTool
 from pydantic import PrivateAttr
 
 from app.agent import StreamingHandler
+from app.agent.tools.tags import ToolTag
 from app.chain import ChainBase
 from app.core.config import settings
 from app.db.user_oper import UserOper
 from app.helper.service import ServiceConfigHelper
 from app.log import logger
 from app.schemas import Notification
-from app.schemas.types import MessageChannel
+from app.schemas.types import MessageChannel, NotificationType
 
 
 class ToolChain(ChainBase):
@@ -26,7 +28,6 @@ class ToolChain(ChainBase):
 # 单个工具结果的兜底上限。各工具仍应优先在自身逻辑中分页或摘要化；
 # 这里用于拦截遗漏路径，避免超大结果直接进入模型上下文。
 DEFAULT_TOOL_RESULT_MAX_CHARS = 64 * 1024
-MIN_TOOL_RESULT_PREVIEW_CHARS = 512
 
 
 def serialize_tool_result_for_agent(result: Any) -> str:
@@ -57,24 +58,40 @@ def format_tool_result_for_agent(
     if not max_chars or max_chars <= 0 or len(formatted_result) <= max_chars:
         return formatted_result
 
-    preview_limit = max(MIN_TOOL_RESULT_PREVIEW_CHARS, max_chars)
-    preview = formatted_result[:preview_limit]
-    payload = {
-        "tool_result_truncated": True,
-        "tool_name": tool_name,
-        "total_chars": len(formatted_result),
-        "returned_chars": len(preview),
-        "content_preview": preview,
-        "message": (
-            f"工具返回内容超过 {max_chars} 字符，已截断为预览；"
-            "请使用更精确的筛选条件、分页参数或专用查询参数继续获取。"
-        ),
-    }
-    return json.dumps(payload, ensure_ascii=False, indent=2)
+    def _dump_preview(preview: str) -> str:
+        """序列化截断结果，并让 returned_chars 与实际预览保持一致。"""
+        payload = {
+            "tool_result_truncated": True,
+            "tool_name": tool_name,
+            "total_chars": len(formatted_result),
+            "returned_chars": len(preview),
+            "content_preview": preview,
+            "message": (
+                f"工具返回内容超过 {max_chars} 字符，已截断为预览；"
+                "请使用更精确的筛选条件、分页参数或专用查询参数继续获取。"
+            ),
+        }
+        return json.dumps(payload, ensure_ascii=False, indent=2)
+
+    # JSON 会转义换行、引号和反斜杠，预览本身等于上限时，最终返回值仍可能
+    # 明显超限。通过二分查找预留包装开销，确保进入模型的最终字符串是硬上限。
+    low = 0
+    high = min(len(formatted_result), max_chars)
+    best_result = _dump_preview("")
+    while low <= high:
+        middle = (low + high) // 2
+        candidate = _dump_preview(formatted_result[:middle])
+        if len(candidate) <= max_chars:
+            best_result = candidate
+            low = middle + 1
+        else:
+            high = middle - 1
+    return best_result
 
 
 # 将常见的阻塞调用按能力域拆分到独立线程池，避免外部慢 IO 抢占同一批 worker。
 _BLOCKING_BUCKET_LIMITS = {
+    "command": 4,
     "default": 4,
     "config": 2,
     "db": 4,
@@ -85,6 +102,7 @@ _BLOCKING_BUCKET_LIMITS = {
     "site": 4,
     "storage": 4,
     "subscribe": 2,
+    "web": 2,
     "workflow": 2,
 }
 _blocking_semaphores = {
@@ -111,6 +129,64 @@ def _get_blocking_executor(bucket: str) -> ThreadPoolExecutor:
         return executor
 
 
+def shutdown_blocking_executors(*, wait: bool = True, cancel_futures: bool = False) -> None:
+    """关闭 Agent 工具阻塞线程池，释放长期运行进程或测试环境中的 worker。"""
+    with _blocking_executor_lock:
+        executors = list(_blocking_executors.values())
+        _blocking_executors.clear()
+
+    for executor in executors:
+        executor.shutdown(wait=wait, cancel_futures=cancel_futures)
+
+
+class ToolExecutionTimeoutError(TimeoutError):
+    """Agent 工具执行超时异常。"""
+
+
+def _get_tool_timeout_seconds() -> Optional[float]:
+    """读取工具执行超时时间，配置为 0 或负数时表示不限制。"""
+    try:
+        timeout = float(settings.LLM_TOOL_TIMEOUT or 0)
+    except (TypeError, ValueError):
+        timeout = 0
+    return timeout if timeout > 0 else None
+
+
+async def run_agent_blocking(
+        bucket: str, func: Callable[..., Any], *args: Any, **kwargs: Any
+) -> Any:
+    """
+    在受控线程池中运行阻塞型同步代码。
+
+    调用方被取消时不会提前释放并发名额，避免底层阻塞调用仍在运行时继续接纳
+    新任务，把同一类慢 IO 的线程池持续打满。
+    """
+    bucket_name = bucket if bucket in _BLOCKING_BUCKET_LIMITS else "default"
+    semaphore = _blocking_semaphores[bucket_name]
+    bound_call = partial(func, *args, **kwargs)
+    loop = asyncio.get_running_loop()
+
+    await semaphore.acquire()
+    try:
+        future = _get_blocking_executor(bucket_name).submit(bound_call)
+    except Exception:
+        semaphore.release()
+        raise
+
+    def _release_semaphore(_future) -> None:
+        try:
+            _future.exception()
+        except Exception:
+            pass
+        try:
+            loop.call_soon_threadsafe(semaphore.release)
+        except RuntimeError:
+            pass
+
+    future.add_done_callback(_release_semaphore)
+    return await asyncio.shield(asyncio.wrap_future(future, loop=loop))
+
+
 class MoviePilotTool(BaseTool, metaclass=ABCMeta):
     """
     MoviePilot专用工具基类（LangChain v1 / langchain_core）
@@ -131,7 +207,31 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         super().__init__(**kwargs)
         self._session_id = session_id
         self._user_id = user_id
-        self._require_admin = getattr(self.__class__, "require_admin", False)
+        # require_admin 在各工具子类以 pydantic 字段声明，pydantic v2 不在类对象上暴露字段值
+        # （getattr(cls, ...) 取不到），必须经实例读取——super().__init__() 已按字段默认填充实例；
+        # getattr 兜底兼容未声明该字段的工具，缺省按非管理员（False）处理。
+        self._require_admin = getattr(self, "require_admin", False)
+        self.tags = self._build_tool_tags()
+
+    @staticmethod
+    def _normalize_tag_values(tags: Optional[Any]) -> set[str]:
+        """规范化 LangChain 工具标签。"""
+        if not tags:
+            return set()
+        if isinstance(tags, (str, ToolTag)):
+            tags = [tags]
+        normalized_tags = set()
+        for tag in tags:
+            if isinstance(tag, ToolTag):
+                normalized_tags.add(tag.value)
+            elif tag:
+                normalized_tags.add(str(tag))
+        return normalized_tags
+
+    def _build_tool_tags(self) -> list[str]:
+        """规范化工具实现中显式声明的标签。"""
+        explicit_tags = self._normalize_tag_values(getattr(self, "tags", None))
+        return sorted(explicit_tags | {ToolTag.AgentTool.value})
 
     def _run(self, *args: Any, **kwargs: Any) -> Any:
         raise NotImplementedError("MoviePilotTool 只支持异步调用，请使用 _arun")
@@ -152,13 +252,9 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
 
         # 获取工具执行提示消息
         tool_message = self.get_tool_message(**kwargs)
-        if not tool_message:
-            explanation = kwargs.get("explanation")
-            if explanation:
-                tool_message = explanation
 
-        # 发送工具执行过程消息
-        if self._stream_handler and self._stream_handler.is_streaming:
+        # 发送工具执行过程消息（流式传输且非最后终结工具时）
+        if self._stream_handler and self._stream_handler.is_streaming and not self.return_direct:
             if settings.AI_AGENT_VERBOSE:
                 if self._stream_handler.is_auto_flushing:
                     # 渠道支持编辑：工具消息追加到 buffer，由定时刷新推送
@@ -211,7 +307,7 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
 
         # 执行具体工具逻辑
         try:
-            result = await self.run(**kwargs)
+            result = await self.run_with_timeout(**kwargs)
             
             # 记录工具执行结果摘要日志
             str_result = serialize_tool_result_for_agent(result)
@@ -221,6 +317,10 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
                 summary = str_result
             logger.info(f"Agent工具 {self.name} 执行完成，结果摘要: {summary}")
             
+        except ToolExecutionTimeoutError as e:
+            error_message = str(e)
+            logger.warning(error_message)
+            result = error_message
         except Exception as e:
             error_message = f"工具执行异常 ({type(e).__name__}): {str(e)}"
             logger.error(f"Tool {self.name} execution failed: {e}", exc_info=True)
@@ -235,22 +335,31 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         获取工具执行时的友好提示消息。
 
         子类可以重写此方法，根据实际参数生成个性化的提示消息。
-        如果返回 None 或空字符串，将回退使用 explanation 参数。
-
         Args:
-            **kwargs: 工具的所有参数（包括 explanation）
+            **kwargs: 工具的所有参数
 
         Returns:
-            str: 友好的提示消息，如果返回 None 或空字符串则使用 explanation
+            str: 友好的提示消息
         """
-        explanation = kwargs.get("explanation")
-        return str(explanation) if explanation else None
+        return None
 
     @abstractmethod
     async def run(self, **kwargs) -> str:
         """子类实现具体的工具执行逻辑"""
         raise NotImplementedError
 
+    async def run_with_timeout(self, **kwargs) -> str:
+        """按系统配置限制单个工具调用的最长执行时间。"""
+        timeout = _get_tool_timeout_seconds()
+        if not timeout:
+            return await self.run(**kwargs)
+        try:
+            return await asyncio.wait_for(self.run(**kwargs), timeout=timeout)
+        except asyncio.TimeoutError as err:
+            raise ToolExecutionTimeoutError(
+                f"工具 {self.name} 执行超时（超过 {timeout:g} 秒），已停止等待结果。"
+            ) from err
+
     @staticmethod
     async def run_blocking(
             bucket: str, func: Callable[..., Any], *args: Any, **kwargs: Any
@@ -258,15 +367,7 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         """
         在受控线程池中运行阻塞型同步代码，避免拖住 FastAPI 主事件循环。
         """
-        bucket_name = bucket if bucket in _BLOCKING_BUCKET_LIMITS else "default"
-        semaphore = _blocking_semaphores[bucket_name]
-        bound_call = partial(func, *args, **kwargs)
-
-        async with semaphore:
-            loop = asyncio.get_running_loop()
-            return await loop.run_in_executor(
-                _get_blocking_executor(bucket_name), bound_call
-            )
+        return await run_agent_blocking(bucket, func, *args, **kwargs)
 
     def set_message_attr(self, channel: str, source: str, username: str):
         """
@@ -290,6 +391,116 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         # 独立的新 dict，跨工具状态（例如质量门槛拒绝标记）无法传播。
         self._agent_context = {} if agent_context is None else agent_context
 
+    async def is_admin_user(self) -> bool:
+        """
+        判断当前工具调用者是否拥有管理员级权限。
+
+        :return: 当前调用者是系统管理员、渠道管理员或显式管理员上下文时返回 True
+        """
+        if bool(self._agent_context.get("is_admin")):
+            return True
+
+        if not self._channel or not self._source:
+            return False
+
+        return await self._has_channel_admin_permission()
+
+    @staticmethod
+    def _resolve_local_path(path: str) -> Path:
+        """
+        解析本地路径并展开符号链接。
+
+        :param path: 用户传入的本地文件或目录路径
+        :return: 规范化后的绝对路径
+        """
+        return Path(path).expanduser().resolve(strict=False)
+
+    @staticmethod
+    def _is_path_relative_to(path: Path, root: Path) -> bool:
+        """
+        判断路径是否位于指定目录内。
+
+        :param path: 待检查路径
+        :param root: 允许访问的根目录
+        :return: 路径在根目录内或等于根目录时返回 True
+        """
+        try:
+            path.relative_to(root)
+            return True
+        except ValueError:
+            return False
+
+    @classmethod
+    def _get_non_admin_local_file_roots(cls) -> list[Path]:
+        """
+        获取普通用户可访问的本地文件根目录。
+
+        :return: 普通用户允许读写的本地目录列表
+        """
+        roots = [
+            settings.CONFIG_PATH / "agent",
+        ]
+        resolved_roots = []
+        for root in roots:
+            resolved_root = cls._resolve_local_path(str(root))
+            if resolved_root not in resolved_roots:
+                resolved_roots.append(resolved_root)
+        return resolved_roots
+
+    async def _check_local_file_access(
+        self, path: str, operation: str = "访问"
+    ) -> tuple[Optional[Path], Optional[str]]:
+        """
+        检查当前用户是否可访问指定本地路径。
+
+        :param path: 用户传入的本地文件或目录路径
+        :param operation: 当前操作名称，用于生成拒绝提示
+        :return: 解析后的路径和拒绝原因；拒绝原因为空表示允许访问
+        """
+        if not path:
+            return None, "错误：路径不能为空"
+
+        resolved_path = self._resolve_local_path(path)
+        if await self.is_admin_user():
+            return resolved_path, None
+
+        allowed_roots = self._get_non_admin_local_file_roots()
+        if any(
+            self._is_path_relative_to(resolved_path, root)
+            for root in allowed_roots
+        ):
+            return resolved_path, None
+
+        allowed_text = "、".join(str(root) for root in allowed_roots)
+        return (
+            resolved_path,
+            f"抱歉，普通用户只能{operation}Agent配置目录内的文件或目录：{allowed_text}",
+        )
+
+    async def _check_local_storage_access(
+        self,
+        path: str,
+        storage: Optional[str] = "local",
+        operation: str = "访问",
+    ) -> tuple[Optional[Path], Optional[str]]:
+        """
+        检查当前用户是否可访问指定存储路径。
+
+        :param path: 用户传入的文件或目录路径
+        :param storage: 存储类型，普通用户只允许 local
+        :param operation: 当前操作名称，用于生成拒绝提示
+        :return: 本地存储时返回解析后的路径和拒绝原因；远程存储无本地路径
+        """
+        if (storage or "local") != "local":
+            if await self.is_admin_user():
+                return None, None
+            return (
+                None,
+                f"抱歉，普通用户只能{operation}本地Agent配置目录，不能访问远程存储。",
+            )
+
+        return await self._check_local_file_access(path=path, operation=operation)
+
     async def _check_permission(self) -> Optional[str]:
         """
         检查用户权限：
@@ -302,9 +513,28 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         if not self._require_admin:
             return None
 
+        if await self.is_admin_user():
+            return None
+
         if not self._channel or not self._source:
             return None
 
+        return (
+            "抱歉，您没有执行此工具的权限。"
+            "只有渠道管理员或系统管理员才能执行工具操作。"
+            "如需执行工具，请联系管理员将您的用户ID添加到渠道管理员列表中（设定 -> 通知 -> 对应渠道配置 -> 管理员名单），"
+            "或联系系统管理员为您设置管理员权限。"
+        )
+
+    async def _has_channel_admin_permission(self) -> bool:
+        """
+        检查当前消息渠道身份是否具备管理员权限。
+
+        :return: 当前渠道用户是渠道管理员、系统管理员或默认接收人时返回 True
+        """
+        if not self._channel or not self._source:
+            return False
+
         # 渠道配置来自 SystemConfigOper 内存缓存，可以直接读取；
         # 只有用户信息需要走异步数据库查询。
         user_id_str = str(self._user_id) if self._user_id else None
@@ -328,7 +558,7 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
                 break
 
         if not channel_type:
-            return None
+            return False
 
         admin_key_map = {
             "telegram": "TELEGRAM_ADMINS",
@@ -348,6 +578,9 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
             "wechat": "WECHAT_BOT_CHAT_ID",
             "feishu": "FEISHU_OPEN_ID",
             "wechatclawbot": "WECHATCLAWBOT_DEFAULT_TARGET",
+            "discord": "DISCORD_CHANNEL_ID",
+            "slack": "SLACK_CHANNEL",
+            "qqbot": "QQ_OPENID",
         }
 
         admin_key = admin_key_map.get(channel_type)
@@ -365,7 +598,7 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
                             if aid.strip()
                         ]
                         if user_id_str and user_id_str in admin_list:
-                            return None
+                            return True
 
                         user = (
                             await UserOper().async_get_by_name(self._username)
@@ -373,14 +606,9 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
                             else None
                         )
                         if user and user.is_superuser:
-                            return None
+                            return True
 
-                        return (
-                            "抱歉，您没有执行此工具的权限。"
-                            "只有渠道管理员或系统管理员才能执行工具操作。"
-                            "如需执行工具，请联系渠道管理员将您的用户ID添加到渠道管理员列表中，"
-                            "或联系系统管理员为您设置权限。"
-                        )
+                        return False
                     else:
                         user = (
                             await UserOper().async_get_by_name(self._username)
@@ -388,37 +616,67 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
                             else None
                         )
                         if user and user.is_superuser:
-                            return None
+                            return True
 
                         if user_id_key:
                             config_user_id = config.config.get(user_id_key)
                             if config_user_id and str(config_user_id) == user_id_str:
-                                return None
+                                return True
 
-                        return (
-                            "抱歉，您没有执行此工具的权限。"
-                            "只有系统管理员才能执行工具操作。"
-                            "如需执行工具，请联系系统管理员为您设置权限。"
-                        )
+                        return False
         except Exception as e:
             logger.error(f"检查权限失败: {e}")
 
-        return None
+        return False
+
+    async def send_notification_message(self, notification: Notification) -> None:
+        """
+        发送工具通知消息。
+
+        WebAgent 渠道没有后端模块实例，前端流式面板通过 Agent 上下文中的
+        回调直接接收通知；无渠道的后台任务清空渠道侧定位信息后交由消息链广播，
+        其它渠道继续走统一消息链。
+        """
+        callback = self._agent_context.get("notification_callback")
+        if (
+            self._channel == MessageChannel.WebAgent.value
+            and callable(callback)
+        ):
+            callback(notification)
+            return
+
+        if not self._channel or not self._source:
+            notification = notification.model_copy(
+                update={
+                    "channel": None,
+                    "source": None,
+                    "userid": None,
+                    "username": notification.username
+                    or self._username
+                    or settings.SUPERUSER,
+                    "original_message_id": None,
+                    "original_chat_id": None,
+                }
+            )
+
+        await ToolChain().async_post_message(notification)
 
     async def send_tool_message(
         self, message: str, title: str = "", image: Optional[str] = None
-    ):
+    ) -> None:
         """
         发送工具消息
         """
-        await ToolChain().async_post_message(
+        await self.send_notification_message(
             Notification(
                 channel=self._channel,
                 source=self._source,
+                mtype=NotificationType.Agent,
                 userid=self._user_id,
                 username=self._username,
                 title=title,
                 text=message,
                 image=image,
+                save_history=False,
             )
         )

app/agent/tools/factory.py

@@ -1,6 +1,6 @@
-from typing import List, Callable
+from typing import Callable, List, Optional, Type
 
-from app.agent.tools.impl.add_download import AddDownloadTool
+from app.agent.tools.impl.add_download_tasks import AddDownloadTasksTool
 from app.agent.tools.impl.add_subscribe import AddSubscribeTool
 from app.agent.tools.impl.update_subscribe import UpdateSubscribeTool
 from app.agent.tools.impl.search_subscribe import SearchSubscribeTool
@@ -37,22 +37,28 @@ 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.recognize_captcha import RecognizeCaptchaTool
 from app.agent.tools.impl.send_message import SendMessageTool
 from app.agent.tools.impl.ask_user_choice import AskUserChoiceTool
 from app.agent.tools.impl.send_local_file import SendLocalFileTool
 from app.agent.tools.impl.send_voice_message import SendVoiceMessageTool
+from app.agent.tools.impl.create_agent_task import CreateAgentTaskTool
+from app.agent.tools.impl.delete_agent_task import DeleteAgentTaskTool
+from app.agent.tools.impl.query_agent_tasks import QueryAgentTasksTool
 from app.agent.tools.impl.query_schedulers import QuerySchedulersTool
+from app.agent.tools.impl.run_agent_task import RunAgentTaskTool
 from app.agent.tools.impl.run_scheduler import RunSchedulerTool
+from app.agent.tools.impl.update_agent_task import UpdateAgentTaskTool
 from app.agent.tools.impl.query_workflows import QueryWorkflowsTool
 from app.agent.tools.impl.run_workflow import RunWorkflowTool
 from app.agent.tools.impl.query_personas import QueryPersonasTool
 from app.agent.tools.impl.switch_persona import SwitchPersonaTool
 from app.agent.tools.impl.update_persona_definition import UpdatePersonaDefinitionTool
 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_tasks import DeleteDownloadTasksTool
 from app.agent.tools.impl.delete_download_history import DeleteDownloadHistoryTool
 from app.agent.tools.impl.delete_transfer_history import DeleteTransferHistoryTool
-from app.agent.tools.impl.modify_download import ModifyDownloadTool
+from app.agent.tools.impl.update_download_tasks import UpdateDownloadTasksTool
 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
@@ -74,6 +80,7 @@ from app.agent.tools.impl.uninstall_plugin import UninstallPluginTool
 from app.agent.tools.impl.run_slash_command import RunSlashCommandTool
 from app.agent.tools.impl.list_slash_commands import ListSlashCommandsTool
 from app.agent.tools.impl.query_custom_identifiers import QueryCustomIdentifiersTool
+from app.agent.tools.impl.query_doctor_report import QueryDoctorReportTool
 from app.agent.tools.impl.update_custom_identifiers import UpdateCustomIdentifiersTool
 from app.agent.tools.impl.query_system_settings import QuerySystemSettingsTool
 from app.agent.tools.impl.update_system_settings import UpdateSystemSettingsTool
@@ -90,8 +97,92 @@ class MoviePilotToolFactory:
     MoviePilot工具工厂
     """
 
+    BUILTIN_TOOL_CLASSES: tuple[Type[MoviePilotTool], ...] = (
+        SearchMediaTool,
+        SearchPersonTool,
+        SearchPersonCreditsTool,
+        RecognizeMediaTool,
+        ScrapeMetadataTool,
+        QueryEpisodeScheduleTool,
+        QueryMediaDetailTool,
+        AddSubscribeTool,
+        UpdateSubscribeTool,
+        SearchSubscribeTool,
+        SearchTorrentsTool,
+        GetSearchResultsTool,
+        SearchWebTool,
+        RecognizeCaptchaTool,
+        AddDownloadTasksTool,
+        QuerySubscribesTool,
+        QuerySubscribeSharesTool,
+        QueryPopularSubscribesTool,
+        QueryBuiltinFilterRulesTool,
+        QueryCustomFilterRulesTool,
+        QueryRuleGroupsTool,
+        AddCustomFilterRuleTool,
+        UpdateCustomFilterRuleTool,
+        DeleteCustomFilterRuleTool,
+        AddRuleGroupTool,
+        UpdateRuleGroupTool,
+        DeleteRuleGroupTool,
+        QuerySubscribeHistoryTool,
+        DeleteSubscribeTool,
+        QueryDownloadTasksTool,
+        DeleteDownloadTasksTool,
+        DeleteDownloadHistoryTool,
+        DeleteTransferHistoryTool,
+        UpdateDownloadTasksTool,
+        QueryDownloadersTool,
+        QuerySitesTool,
+        UpdateSiteTool,
+        QuerySiteUserdataTool,
+        TestSiteTool,
+        UpdateSiteCookieTool,
+        GetRecommendationsTool,
+        QueryLibraryExistsTool,
+        QueryLibraryLatestTool,
+        QueryDirectorySettingsTool,
+        ListDirectoryTool,
+        QueryTransferHistoryTool,
+        TransferFileTool,
+        SendMessageTool,
+        CreateAgentTaskTool,
+        QueryAgentTasksTool,
+        UpdateAgentTaskTool,
+        RunAgentTaskTool,
+        DeleteAgentTaskTool,
+        QuerySchedulersTool,
+        RunSchedulerTool,
+        QueryWorkflowsTool,
+        RunWorkflowTool,
+        QueryPersonasTool,
+        SwitchPersonaTool,
+        UpdatePersonaDefinitionTool,
+        ExecuteCommandTool,
+        EditFileTool,
+        WriteFileTool,
+        ReadFileTool,
+        BrowseWebpageTool,
+        QueryInstalledPluginsTool,
+        QueryMarketPluginsTool,
+        QueryPluginCapabilitiesTool,
+        QueryPluginConfigTool,
+        UpdatePluginConfigTool,
+        ReloadPluginTool,
+        QueryPluginDataTool,
+        InstallPluginTool,
+        UninstallPluginTool,
+        RunSlashCommandTool,
+        ListSlashCommandsTool,
+        QueryDoctorReportTool,
+        QueryCustomIdentifiersTool,
+        UpdateCustomIdentifiersTool,
+        QuerySystemSettingsTool,
+        UpdateSystemSettingsTool,
+    )
+
     # 这些通用工具需要始终保留，避免大工具集裁剪后让 Agent 丢失基础的
-    # 文件系统、命令执行或交互确认能力。AskUserChoiceTool 仅在支持按钮
+    # 文件系统、命令执行、历史检索或交互确认能力。AskUserChoiceTool 仅在支持按钮
     # 的渠道中才会实际注入，因此后续会再按已加载工具做一次求交集。
     TOOL_SELECTOR_ALWAYS_INCLUDE_NAMES = (
         "list_directory",
@@ -100,10 +191,12 @@ class MoviePilotToolFactory:
         "edit_file",
         "execute_command",
         "ask_user_choice",
+        "create_agent_task",
+        "query_agent_tasks",
     )
 
     @staticmethod
-    def _should_enable_choice_tool(channel: str = None) -> bool:
+    def _should_enable_choice_tool(channel: Optional[str] = None) -> bool:
         if not channel:
             return False
         try:
@@ -133,8 +226,24 @@ class MoviePilotToolFactory:
             if tool_name in available_tool_names
         ]
 
-    @staticmethod
+    @classmethod
+    def _get_builtin_tool_classes(
+        cls, channel: Optional[str] = None
+    ) -> list[Type[MoviePilotTool]]:
+        """
+        返回当前渠道可用的内置工具类清单。
+        """
+        tool_definitions = list(cls.BUILTIN_TOOL_CLASSES)
+        if cls._should_enable_choice_tool(channel):
+            tool_definitions.append(AskUserChoiceTool)
+        tool_definitions.append(SendLocalFileTool)
+        if AgentCapabilityManager.supports_audio_output():
+            tool_definitions.append(SendVoiceMessageTool)
+        return tool_definitions
+
+    @classmethod
     def create_tools(
+        cls,
         session_id: str,
         user_id: str,
         channel: str = None,
@@ -148,87 +257,7 @@ class MoviePilotToolFactory:
         创建MoviePilot工具列表
         """
         tools = []
-        tool_definitions = [
-            SearchMediaTool,
-            SearchPersonTool,
-            SearchPersonCreditsTool,
-            RecognizeMediaTool,
-            ScrapeMetadataTool,
-            QueryEpisodeScheduleTool,
-            QueryMediaDetailTool,
-            AddSubscribeTool,
-            UpdateSubscribeTool,
-            SearchSubscribeTool,
-            SearchTorrentsTool,
-            GetSearchResultsTool,
-            SearchWebTool,
-            AddDownloadTool,
-            QuerySubscribesTool,
-            QuerySubscribeSharesTool,
-            QueryPopularSubscribesTool,
-            QueryBuiltinFilterRulesTool,
-            QueryCustomFilterRulesTool,
-            QueryRuleGroupsTool,
-            AddCustomFilterRuleTool,
-            UpdateCustomFilterRuleTool,
-            DeleteCustomFilterRuleTool,
-            AddRuleGroupTool,
-            UpdateRuleGroupTool,
-            DeleteRuleGroupTool,
-            QuerySubscribeHistoryTool,
-            DeleteSubscribeTool,
-            QueryDownloadTasksTool,
-            DeleteDownloadTool,
-            DeleteDownloadHistoryTool,
-            DeleteTransferHistoryTool,
-            ModifyDownloadTool,
-            QueryDownloadersTool,
-            QuerySitesTool,
-            UpdateSiteTool,
-            QuerySiteUserdataTool,
-            TestSiteTool,
-            UpdateSiteCookieTool,
-            GetRecommendationsTool,
-            QueryLibraryExistsTool,
-            QueryLibraryLatestTool,
-            QueryDirectorySettingsTool,
-            ListDirectoryTool,
-            QueryTransferHistoryTool,
-            TransferFileTool,
-            SendMessageTool,
-            QuerySchedulersTool,
-            RunSchedulerTool,
-            QueryWorkflowsTool,
-            RunWorkflowTool,
-            QueryPersonasTool,
-            SwitchPersonaTool,
-            UpdatePersonaDefinitionTool,
-            ExecuteCommandTool,
-            EditFileTool,
-            WriteFileTool,
-            ReadFileTool,
-            BrowseWebpageTool,
-            QueryInstalledPluginsTool,
-            QueryMarketPluginsTool,
-            QueryPluginCapabilitiesTool,
-            QueryPluginConfigTool,
-            UpdatePluginConfigTool,
-            ReloadPluginTool,
-            QueryPluginDataTool,
-            InstallPluginTool,
-            UninstallPluginTool,
-            RunSlashCommandTool,
-            ListSlashCommandsTool,
-            QueryCustomIdentifiersTool,
-            UpdateCustomIdentifiersTool,
-            QuerySystemSettingsTool,
-            UpdateSystemSettingsTool,
-        ]
-        if MoviePilotToolFactory._should_enable_choice_tool(channel):
-            tool_definitions.append(AskUserChoiceTool)
-        tool_definitions.append(SendLocalFileTool)
-        if AgentCapabilityManager.supports_audio_output():
-            tool_definitions.append(SendVoiceMessageTool)
+        tool_definitions = cls._get_builtin_tool_classes(channel)
         # 创建内置工具
         for ToolClass in tool_definitions:
             tool = ToolClass(session_id=session_id, user_id=user_id)
@@ -275,9 +304,9 @@ class MoviePilotToolFactory:
 
         builtin_tools_count = len(tool_definitions)
         if plugin_tools_count > 0:
-            logger.info(
+            logger.debug(
                 f"成功创建 {len(tools)} 个MoviePilot工具（内置工具: {builtin_tools_count} 个，插件工具: {plugin_tools_count} 个）"
             )
         else:
-            logger.info(f"成功创建 {len(tools)} 个MoviePilot工具")
+            logger.debug(f"成功创建 {len(tools)} 个MoviePilot工具")
         return tools

app/agent/tools/impl/_command_safety.py

@@ -0,0 +1,88 @@
+"""Agent 命令工具的安全校验逻辑。"""
+
+from __future__ import annotations
+
+import os.path
+import re
+import shlex
+
+
+COMMAND_FORBIDDEN_KEYWORDS = (
+    ":(){ :|:& };:",
+    "dd if=/dev/zero",
+    "mkfs",
+    "reboot",
+    "shutdown",
+)
+
+COMMAND_DANGEROUS_PATTERNS = (
+    re.compile(r"\brm\s+[^;&|]*-[^\s;&|]*[rR][fF]?[^\s;&|]*\s+/(?:\s|$|[;&|])"),
+    re.compile(r"\bdd\s+[^;&|]*(?:of=/dev/(?:sd[a-z]\d*|nvme\d+n\d+p?\d*|disk\d+)|if=/dev/zero)"),
+    re.compile(r"\b(?:mkfs|fdisk|parted|diskutil)\b"),
+    re.compile(r"\b(?:chmod|chown)\s+[^;&|]*-R[^;&|]*\s+/(?:\s|$|[;&|])"),
+    re.compile(r"\b(?:reboot|shutdown|halt|poweroff)\b"),
+)
+
+
+def _command_tokens(command: str) -> list[str]:
+    """尽力解析 shell 命令 token，解析失败时退回空白分割。"""
+    try:
+        return shlex.split(command, posix=True)
+    except ValueError:
+        return re.split(r"\s+", command.strip())
+
+
+def _contains_recursive_root_delete(command: str) -> bool:
+    """识别递归删除根目录或一级目录的 rm 命令。"""
+    tokens = _command_tokens(command)
+    if not any(token == "rm" or token.endswith("/rm") for token in tokens):
+        return False
+    has_recursive = any(
+        token.startswith("-") and ("r" in token or "R" in token)
+        for token in tokens
+    )
+    if not has_recursive:
+        return False
+
+    for token in tokens:
+        clean_token = re.match(r"^([^;|&><]+)", token)
+        if not clean_token:
+            continue
+        path_value = clean_token.group(1).strip("\"'")
+        if not path_value.startswith("/"):
+            continue
+        norm_path = os.path.normpath(path_value)
+        if norm_path == "/" or re.match(r"^/[^/]+$", norm_path):
+            return True
+    return False
+
+
+def detect_dangerous_command(command: str) -> str:
+    """返回危险命令原因，安全时返回空字符串。"""
+    normalized = str(command or "").strip()
+    if not normalized:
+        return "命令不能为空"
+    for keyword in COMMAND_FORBIDDEN_KEYWORDS:
+        if keyword in normalized:
+            return f"命令包含禁止使用的关键字 '{keyword}'"
+    if _contains_recursive_root_delete(normalized):
+        return "命令疑似递归删除根目录或一级目录"
+    for pattern in COMMAND_DANGEROUS_PATTERNS:
+        if pattern.search(normalized):
+            return "命令匹配高危系统操作模式"
+    return ""
+
+
+def validate_command_safety(command: str, *, confirmed: bool = False) -> None:
+    """
+    校验 shell 命令安全性。
+
+    :param command: 待执行命令
+    :param confirmed: 是否已经通过显式参数确认高危操作
+    """
+    reason = detect_dangerous_command(command)
+    if not reason:
+        return
+    if confirmed and reason != "命令不能为空":
+        return
+    raise ValueError(f"{reason}。如确认需要执行，请设置 confirm_dangerous=true")

app/agent/tools/impl/_file_write_utils.py

@@ -0,0 +1,53 @@
+"""Agent 文件写入工具的共享辅助函数。"""
+
+import hashlib
+import os
+import tempfile
+from pathlib import Path
+
+
+class FileVersionConflictError(RuntimeError):
+    """目标文件在准备写入期间发生变化。"""
+
+
+def calculate_file_sha256(path: Path) -> str:
+    """计算文件原始字节的 SHA-256，用于检测陈旧写入。"""
+    digest = hashlib.sha256()
+    with path.open("rb") as file_handle:
+        for chunk in iter(lambda: file_handle.read(64 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def atomic_write_text(
+    path: Path,
+    content: str,
+    expected_sha256: str | None = None,
+) -> None:
+    """校验目标版本后，在同目录写入临时文件并原子替换文本。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temp_name = tempfile.mkstemp(
+        dir=path.parent,
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+    )
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as file_handle:
+            file_handle.write(content)
+            file_handle.flush()
+            os.fsync(file_handle.fileno())
+
+        if expected_sha256:
+            if (
+                not path.is_file()
+                or calculate_file_sha256(path).casefold()
+                != expected_sha256.casefold()
+            ):
+                raise FileVersionConflictError(str(path))
+        if path.exists():
+            os.chmod(temp_path, path.stat().st_mode)
+        os.replace(temp_path, path)
+    finally:
+        if temp_path.exists():
+            temp_path.unlink()

app/agent/tools/impl/_filter_rule_utils.py

@@ -5,8 +5,7 @@ import re
 from typing import Any, Dict, Iterable, Optional
 
 from app.core.event import eventmanager
-from app.db import AsyncSessionFactory
-from app.db.models.subscribe import Subscribe
+from app.db.subscribe_oper import SubscribeOper
 from app.db.systemconfig_oper import SystemConfigOper
 from app.helper.rule import RuleHelper
 from app.modules.filter.RuleParser import RuleParser
@@ -284,23 +283,22 @@ async def collect_rule_group_usages(
             continue
         ensure_usage(name)["used_in_global_best_version"] = True
 
-    async with AsyncSessionFactory() as db:
-        subscribes = await Subscribe.async_list(db)
-        for subscribe in subscribes:
-            filter_groups = subscribe.filter_groups or []
-            for name in filter_groups:
-                if target_names and name not in target_names:
-                    continue
-                ensure_usage(name)["subscribes"].append(
-                    {
-                        "subscribe_id": subscribe.id,
-                        "name": subscribe.name,
-                        "season": subscribe.season,
-                        "type": subscribe.type,
-                        "username": subscribe.username,
-                        "best_version": bool(subscribe.best_version),
-                    }
-                )
+    subscribes = await SubscribeOper().async_list()
+    for subscribe in subscribes:
+        filter_groups = subscribe.filter_groups or []
+        for name in filter_groups:
+            if target_names and name not in target_names:
+                continue
+            ensure_usage(name)["subscribes"].append(
+                {
+                    "subscribe_id": subscribe.id,
+                    "name": subscribe.name,
+                    "season": subscribe.season,
+                    "type": subscribe.type,
+                    "username": subscribe.username,
+                    "best_version": bool(subscribe.best_version),
+                }
+            )
 
     return usage_map
 
@@ -482,22 +480,22 @@ async def rename_rule_group_references(old_name: str, new_name: str) -> dict:
             await save_system_config(config_key, updated)
             changed["global_settings"][config_key.value] = updated
 
-    async with AsyncSessionFactory() as db:
-        subscribes = await Subscribe.async_list(db)
-        for subscribe in subscribes:
-            original = subscribe.filter_groups or []
-            updated = replace_group_name_in_list(original, old_name, new_name)
-            if updated == original:
-                continue
-            await subscribe.async_update(db, {"filter_groups": updated})
-            changed["subscribes"].append(
-                {
-                    "subscribe_id": subscribe.id,
-                    "name": subscribe.name,
-                    "season": subscribe.season,
-                    "filter_groups": updated,
-                }
-            )
+    subscribe_oper = SubscribeOper()
+    subscribes = await subscribe_oper.async_list()
+    for subscribe in subscribes:
+        original = subscribe.filter_groups or []
+        updated = replace_group_name_in_list(original, old_name, new_name)
+        if updated == original:
+            continue
+        await subscribe_oper.async_update_filter_groups(subscribe.id, updated)
+        changed["subscribes"].append(
+            {
+                "subscribe_id": subscribe.id,
+                "name": subscribe.name,
+                "season": subscribe.season,
+                "filter_groups": updated,
+            }
+        )
 
     return changed
 
@@ -520,21 +518,21 @@ async def remove_rule_group_references(group_name: str) -> dict:
             await save_system_config(config_key, updated)
             changed["global_settings"][config_key.value] = updated
 
-    async with AsyncSessionFactory() as db:
-        subscribes = await Subscribe.async_list(db)
-        for subscribe in subscribes:
-            original = subscribe.filter_groups or []
-            updated = [value for value in original if value != group_name]
-            if updated == original:
-                continue
-            await subscribe.async_update(db, {"filter_groups": updated})
-            changed["subscribes"].append(
-                {
-                    "subscribe_id": subscribe.id,
-                    "name": subscribe.name,
-                    "season": subscribe.season,
-                    "filter_groups": updated,
-                }
-            )
+    subscribe_oper = SubscribeOper()
+    subscribes = await subscribe_oper.async_list()
+    for subscribe in subscribes:
+        original = subscribe.filter_groups or []
+        updated = [value for value in original if value != group_name]
+        if updated == original:
+            continue
+        await subscribe_oper.async_update_filter_groups(subscribe.id, updated)
+        changed["subscribes"].append(
+            {
+                "subscribe_id": subscribe.id,
+                "name": subscribe.name,
+                "season": subscribe.season,
+                "filter_groups": updated,
+            }
+        )
 
     return changed

app/agent/tools/impl/_plugin_tool_utils.py

@@ -1,6 +1,5 @@
 """插件 Agent 工具共享辅助方法"""
 
-import asyncio
 import json
 import shutil
 from typing import Any, Optional
@@ -8,6 +7,7 @@ from typing import Any, Optional
 from app.core.config import settings
 from app.core.plugin import PluginManager
 from app.db.systemconfig_oper import SystemConfigOper
+from app.helper.server import MoviePilotServerHelper
 from app.helper.plugin import PluginHelper
 from app.schemas.types import SystemConfigKey
 
@@ -103,6 +103,79 @@ def summarize_plugin(plugin: Any) -> dict[str, Any]:
     }
 
 
+def _merge_plugin_source_metadata(plugin: Any, source_plugin: Any) -> Any:
+    """
+    将插件市场或本地仓库中的来源元数据合并到已安装插件对象。
+    """
+    repo_url = getattr(source_plugin, "repo_url", None)
+    if repo_url:
+        setattr(plugin, "repo_url", repo_url)
+
+    for attr in (
+        "has_update",
+        "release",
+        "system_version",
+        "system_version_compatible",
+        "system_version_message",
+    ):
+        value = getattr(source_plugin, attr, None)
+        if value is not None:
+            setattr(plugin, attr, value)
+
+    return plugin
+
+
+def _map_plugins_by_id(plugins: list[Any]) -> dict[str, Any]:
+    """
+    按插件 ID 建立稳定映射，保留同 ID 首个候选来源。
+    """
+    plugin_map: dict[str, Any] = {}
+    for plugin in plugins:
+        plugin_id = getattr(plugin, "id", None)
+        if plugin_id and plugin_id not in plugin_map:
+            plugin_map[plugin_id] = plugin
+    return plugin_map
+
+
+async def enrich_installed_plugin_sources(
+    installed_plugins: list[Any],
+    force_refresh: bool = False,
+) -> list[Any]:
+    """
+    为已安装插件补齐安装来源仓库地址。
+
+    本地插件对象只包含运行目录中的静态元数据，通常没有 repo_url。这里按需从
+    本地插件仓库和插件市场补齐来源，保证 Agent 后续安装、升级判断可以拿到仓库地址。
+    """
+    missing_source_plugins = [
+        plugin for plugin in installed_plugins if not getattr(plugin, "repo_url", None)
+    ]
+    if not missing_source_plugins:
+        return installed_plugins
+
+    plugin_manager = PluginManager()
+    local_repo_map = _map_plugins_by_id(plugin_manager.get_local_repo_plugins())
+    for plugin in missing_source_plugins:
+        source_plugin = local_repo_map.get(getattr(plugin, "id", None))
+        if source_plugin:
+            _merge_plugin_source_metadata(plugin, source_plugin)
+
+    missing_source_plugins = [
+        plugin for plugin in installed_plugins if not getattr(plugin, "repo_url", None)
+    ]
+    if not missing_source_plugins:
+        return installed_plugins
+
+    market_plugins = await plugin_manager.async_get_online_plugins(force=force_refresh)
+    market_map = _map_plugins_by_id(market_plugins or [])
+    for plugin in missing_source_plugins:
+        source_plugin = market_map.get(getattr(plugin, "id", None))
+        if source_plugin:
+            _merge_plugin_source_metadata(plugin, source_plugin)
+
+    return installed_plugins
+
+
 async def load_market_plugins(force_refresh: bool = False) -> list[Any]:
     """
     聚合插件市场与本地插件仓库中的候选插件。
@@ -230,7 +303,7 @@ async def install_plugin_runtime(
     refreshed_only = False
     if not force and plugin_id in plugin_manager.get_plugin_ids():
         refreshed_only = True
-        await plugin_helper.async_install_reg(pid=plugin_id, repo_url=repo_url)
+        await MoviePilotServerHelper.async_install_plugin_reg(plugin_id=plugin_id, repo_url=repo_url)
         message = "插件已存在，已刷新加载"
     else:
         if not repo_url:
@@ -242,6 +315,7 @@ async def install_plugin_runtime(
         )
         if not state:
             return False, message, False
+        await MoviePilotServerHelper.async_install_plugin_reg(plugin_id=plugin_id, repo_url=repo_url)
 
     if plugin_id not in install_plugins:
         install_plugins.append(plugin_id)
@@ -249,7 +323,9 @@ async def install_plugin_runtime(
             SystemConfigKey.UserInstalledPlugins, install_plugins
         )
 
-    await asyncio.to_thread(reload_plugin_runtime, plugin_id)
+    from app.agent.tools.base import run_agent_blocking
+
+    await run_agent_blocking("plugin", reload_plugin_runtime, plugin_id)
     return True, message or "插件安装成功", refreshed_only
 
 

app/agent/tools/impl/_system_setting_utils.py

@@ -1,7 +1,7 @@
 """系统设置工具共用的键解析与分组元数据。"""
 
 from dataclasses import dataclass
-from typing import Optional
+from typing import Any, Optional
 
 from app.core.config import Settings
 from app.schemas.types import SystemConfigKey
@@ -15,6 +15,7 @@ class SettingSpec:
     source: str
     group: str
     label: str
+    systemconfig_key: Optional[SystemConfigKey] = None
 
 
 SYSTEMCONFIG_SETTING_METADATA = {
@@ -58,6 +59,10 @@ SYSTEMCONFIG_SETTING_METADATA = {
         "group": "ai_agent",
         "label": "AI 智能体配置",
     },
+    SystemConfigKey.AIAgentMcpServers.value: {
+        "group": "ai_agent",
+        "label": "AI 智能体外部 MCP 服务器",
+    },
     SystemConfigKey.CustomIdentifiers.value: {
         "group": "custom_identifiers",
         "label": "自定义识别词",
@@ -234,6 +239,7 @@ def _build_specs() -> tuple[dict[str, SettingSpec], dict[str, SettingSpec]]:
             source="systemconfig",
             group=metadata.get("group", "misc"),
             label=metadata.get("label", item.value),
+            systemconfig_key=item,
         )
     return core_specs, system_specs
 
@@ -333,3 +339,57 @@ def list_setting_specs(
 
 def get_default_list_match_field(setting_key: str) -> Optional[str]:
     return LIST_ITEM_MATCH_FIELD_DEFAULTS.get(setting_key)
+
+
+SECRET_KEYWORDS = (
+    "api_key",
+    "apikey",
+    "token",
+    "secret",
+    "password",
+    "passwd",
+    "cookie",
+    "authorization",
+    "refresh_token",
+    "access_token",
+)
+
+
+def is_secret_setting_key(key: str) -> bool:
+    """判断设置键名是否疑似敏感字段。"""
+    normalized = _normalize_token(key)
+    return any(keyword in normalized for keyword in SECRET_KEYWORDS)
+
+
+def redact_secret_value(value: Any, *, redact_scalar: bool = False) -> Any:
+    """递归脱敏配置值中的密钥、Cookie、Token 等敏感字段。"""
+    if isinstance(value, dict):
+        return {
+            key: "***"
+            if is_secret_setting_key(str(key))
+            else redact_secret_value(item, redact_scalar=redact_scalar)
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [
+            redact_secret_value(item, redact_scalar=redact_scalar)
+            for item in value
+        ]
+    if isinstance(value, str):
+        return "***" if value and redact_scalar else value
+    return value
+
+
+def should_redact_setting(spec: SettingSpec, value: Any) -> bool:
+    """判断某项设置在默认查询响应中是否需要脱敏。"""
+    if is_secret_setting_key(spec.key):
+        return True
+    if isinstance(value, dict):
+        return any(is_secret_setting_key(str(key)) for key in value.keys())
+    if isinstance(value, list):
+        return any(
+            should_redact_setting(spec, item)
+            for item in value
+            if isinstance(item, dict)
+        )
+    return False

app/agent/tools/impl/_terminal_session.py

@@ -13,6 +13,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Optional
 
+from app.agent.tools.impl._command_safety import validate_command_safety
 from app.core.config import settings
 from app.log import logger
 
@@ -34,14 +35,6 @@ TERMINAL_PTY_POLL_INTERVAL = 0.05
 TERMINAL_WAIT_DEFAULT_MS = 1000
 TERMINAL_WAIT_MAX_MS = 60 * 1000
 TERMINAL_KILL_GRACE_SECONDS = 3
-TERMINAL_FORBIDDEN_KEYWORDS = (
-    "rm -rf /",
-    ":(){ :|:& };:",
-    "dd if=/dev/zero",
-    "mkfs",
-    "reboot",
-    "shutdown",
-)
 
 
 @dataclass
@@ -176,13 +169,9 @@ class _TerminalSessionManager:
         return merged_env
 
     @staticmethod
-    def _validate_command(command: str) -> None:
+    def _validate_command(command: str, *, confirmed: bool = False) -> None:
         """拒绝明显危险或空白命令。"""
-        if not command or not command.strip():
-            raise ValueError("命令不能为空")
-        for keyword in TERMINAL_FORBIDDEN_KEYWORDS:
-            if keyword in command:
-                raise ValueError(f"命令包含禁止使用的关键字 '{keyword}'")
+        validate_command_safety(command, confirmed=confirmed)
 
     @staticmethod
     def _set_nonblocking(fd: int) -> None:
@@ -213,9 +202,10 @@ class _TerminalSessionManager:
         cwd: Optional[str] = None,
         env: Optional[dict[str, Any]] = None,
         use_pty: Any = True,
+        confirm_dangerous: bool = False,
     ) -> dict[str, Any]:
         """启动后台命令并立即返回会话 ID。"""
-        self._validate_command(command)
+        self._validate_command(command, confirmed=confirm_dangerous)
         normalized_cwd = self._normalize_cwd(cwd)
         normalized_env = self._build_env(env)
         should_use_pty = self._normalize_bool(use_pty, default=True) and os.name == "posix"
@@ -302,7 +292,8 @@ class _TerminalSessionManager:
         session.wait_task = asyncio.create_task(self._wait_pipe_process(session))
         return session
 
-    async def _read_pty(self, session: _TerminalSession) -> None:
+    @staticmethod
+    async def _read_pty(session: _TerminalSession) -> None:
         """持续从 PTY 读取增量输出。"""
         while session.master_fd is not None:
             try:
@@ -312,16 +303,19 @@ class _TerminalSessionManager:
                 continue
             except OSError as err:
                 if err.errno not in {errno.EIO, errno.EBADF}:
-                    logger.debug("PTY 输出读取异常: session_id=%s, error=%s", session.session_id, err)
+                    logger.debug(
+                        f"PTY 输出读取异常: session_id={session.session_id}, "
+                        f"error={err}"
+                    )
                 break
 
             if not data:
                 break
             session.append_output("pty", data)
 
+    @staticmethod
     async def _read_pipe(
-        self,
-        session: _TerminalSession,
+            session: _TerminalSession,
         stream: asyncio.StreamReader,
         stream_name: str,
     ) -> None:
@@ -342,7 +336,9 @@ class _TerminalSessionManager:
             session.mark_finished(session.exit_code)
         except Exception as err:
             session.mark_error(str(err))
-            logger.warning("等待 PTY 进程失败: session_id=%s, error=%s", session.session_id, err)
+            logger.warning(
+                f"等待 PTY 进程失败: session_id={session.session_id}, error={err}"
+            )
         finally:
             await self._finish_reader_tasks(session)
             session.close_pty()
@@ -357,11 +353,14 @@ class _TerminalSessionManager:
             session.mark_finished(exit_code)
         except Exception as err:
             session.mark_error(str(err))
-            logger.warning("等待管道进程失败: session_id=%s, error=%s", session.session_id, err)
+            logger.warning(
+                f"等待管道进程失败: session_id={session.session_id}, error={err}"
+            )
         finally:
             await self._finish_reader_tasks(session)
 
-    async def _finish_reader_tasks(self, session: _TerminalSession) -> None:
+    @staticmethod
+    async def _finish_reader_tasks(session: _TerminalSession) -> None:
         """等待输出读取任务退出，超时后取消残留任务。"""
         if not session.reader_tasks:
             return
@@ -531,7 +530,7 @@ class _TerminalSessionManager:
             if len(encoded) > remaining:
                 if remaining > 0:
                     output_parts.append(
-                        encoded[:remaining].decode("utf-8", errors="ignore")
+                        encoded[:remaining].decode("utf-8", errors="replace")
                     )
                 output_truncated = True
                 break

app/agent/tools/impl/_torrent_search_utils.py

@@ -127,8 +127,19 @@ def filter_contexts(items: List[Context],
     return filtered_items
 
 
-def simplify_search_result(context: Context, index: int) -> dict:
-    """精简单条搜索结果"""
+def simplify_search_result(
+    context: Context,
+    index: int,
+    include_description: bool = False,
+) -> dict:
+    """
+    精简单条搜索结果
+
+    :param context: 搜索结果上下文
+    :param index: 搜索结果在原始缓存中的序号
+    :param include_description: 是否返回种子简介
+    :return: 精简后的搜索结果
+    """
     simplified = {}
     torrent_info = context.torrent_info
     meta_info = context.meta_info
@@ -147,6 +158,8 @@ def simplify_search_result(context: Context, index: int) -> dict:
             "freedate_diff": torrent_info.freedate_diff,
             "pubdate": torrent_info.pubdate,
         }
+        if include_description:
+            simplified["torrent_info"]["description"] = torrent_info.description
 
     if media_info:
         simplified["media_info"] = {

app/agent/tools/impl/add_custom_filter_rule.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._filter_rule_utils import (
     get_custom_rules,
     normalize_custom_rule,
@@ -19,8 +20,6 @@ from app.schemas.types import SystemConfigKey
 class AddCustomFilterRuleInput(BaseModel):
     """新增自定义过滤规则工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     rule_id: str = Field(
         ...,
         description="Unique custom rule ID. Only letters and numbers are allowed.",
@@ -46,6 +45,11 @@ class AddCustomFilterRuleInput(BaseModel):
 
 class AddCustomFilterRuleTool(MoviePilotTool):
     name: str = "add_custom_filter_rule"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.FilterRule,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Add a custom filter rule to CustomFilterRules. "
         "The new rule can then be referenced by rule ID inside filter rule groups."

app/agent/tools/impl/add_download_tasks.py

@@ -1,28 +1,29 @@
-"""添加下载工具"""
+"""添加下载任务工具"""
 
 import re
 from pathlib import Path
-from typing import List, Optional, Type
+from typing import List, Optional, Type, Union
 
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
+from app.chain.download import DownloadChain
 from app.chain.media import MediaChain
 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.helper.directory import DirectoryHelper, validate_download_save_path
 from app.log import logger
-from app.schemas import TorrentInfo, FileURI
+from app.schemas import FileURI, TorrentInfo
 from app.utils.crypto import HashUtils
 
 
-class AddDownloadInput(BaseModel):
-    """添加下载工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
+class AddDownloadTasksInput(BaseModel):
+    """添加下载任务工具的输入参数模型"""
+
     torrent_url: List[str] = Field(
         ...,
         description="One or more torrent_url values. Supports refs from get_search_results (`hash:id`) and magnet links."
@@ -35,10 +36,17 @@ class AddDownloadInput(BaseModel):
                                   description="Comma-separated list of labels/tags to assign to the download (optional, e.g., 'movie,hd,bluray')")
 
 
-class AddDownloadTool(MoviePilotTool):
-    name: str = "add_download"
+class AddDownloadTasksTool(MoviePilotTool):
+    """添加下载任务工具"""
+
+    name: str = "add_download_tasks"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.Download,
+        ToolTag.Resource,
+    ]
     description: str = "Add torrent download tasks using refs from get_search_results or magnet links."
-    args_schema: Type[BaseModel] = AddDownloadInput
+    args_schema: Type[BaseModel] = AddDownloadTasksInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据下载参数生成友好的提示消息"""
@@ -151,16 +159,16 @@ class AddDownloadTool(MoviePilotTool):
         prefix = "添加种子任务失败："
         if normalized_error.startswith(prefix):
             normalized_error = normalized_error[len(prefix):].lstrip()
-        if AddDownloadTool._is_magnet_link_input(normalized_error):
+        if AddDownloadTasksTool._is_magnet_link_input(normalized_error):
             normalized_error = ""
         if normalized_error:
             return f"{torrent_ref} {normalized_error}"
-        if AddDownloadTool._is_torrent_ref(torrent_ref):
+        if AddDownloadTasksTool._is_torrent_ref(torrent_ref):
             return torrent_ref
         return ""
 
     @classmethod
-    def _normalize_torrent_urls(cls, torrent_url: Optional[List[str] | str]) -> List[str]:
+    def _normalize_torrent_urls(cls, torrent_url: Optional[Union[List[str], str]]) -> List[str]:
         """统一规范 torrent_url 输入，保留所有非空值"""
         if torrent_url is None:
             return []
@@ -175,8 +183,8 @@ class AddDownloadTool(MoviePilotTool):
     @staticmethod
     def _resolve_direct_download_dir(save_path: Optional[str]) -> Optional[Path]:
         """解析直接下载使用的目录，优先使用 save_path，其次使用默认下载目录"""
-        if save_path:
-            return Path(save_path)
+        if save_path is not None:
+            return Path(validate_download_save_path(save_path))
 
         download_dirs = DirectoryHelper().get_download_dirs()
         if not download_dirs:
@@ -217,6 +225,8 @@ class AddDownloadTool(MoviePilotTool):
         merged_labels: Optional[str],
     ) -> tuple[Optional[str], Optional[str]]:
         """同步提交带上下文的下载任务，避免站点下载与下载器调用阻塞事件循环。"""
+        if save_path is not None:
+            save_path = validate_download_save_path(save_path)
         return DownloadChain().download_single(
             context=context,
             downloader=downloader,
@@ -228,6 +238,7 @@ class AddDownloadTool(MoviePilotTool):
     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}, 参数: torrent_url={torrent_url}, downloader={downloader}, save_path={save_path}, labels={labels}")
 
@@ -236,6 +247,12 @@ class AddDownloadTool(MoviePilotTool):
             if not torrent_inputs:
                 return "错误：torrent_url 不能为空。"
 
+            if save_path is not None:
+                try:
+                    save_path = validate_download_save_path(save_path)
+                except ValueError as err:
+                    return f"参数错误：save_path {str(err)}"
+
             merged_labels = self._merge_labels_with_system_tag(labels)
             success_count = 0
             failed_messages = []

app/agent/tools/impl/add_rule_group.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._filter_rule_utils import (
     build_custom_rule_map,
     collect_rule_group_usages,
@@ -23,8 +24,6 @@ from app.schemas.types import SystemConfigKey
 class AddRuleGroupInput(BaseModel):
     """新增过滤规则组工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     name: str = Field(..., description="New rule group name.")
     rule_string: str = Field(
         ...,
@@ -46,6 +45,11 @@ class AddRuleGroupInput(BaseModel):
 
 class AddRuleGroupTool(MoviePilotTool):
     name: str = "add_rule_group"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.FilterRule,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Add a new filter rule group to UserFilterRuleGroups. "
         "Rule groups are matched level by level from left to right and can be linked to search/subscription flows. "

app/agent/tools/impl/add_subscribe.py

@@ -5,6 +5,7 @@ from typing import List, Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.subscribe import SubscribeChain
 from app.db.user_oper import UserOper
 from app.log import logger
@@ -14,8 +15,6 @@ from app.schemas.types import MediaType, MessageChannel
 class AddSubscribeInput(BaseModel):
     """添加订阅工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     title: str = Field(
         ...,
         description="The title of the media to subscribe to (e.g., 'The Matrix', 'Breaking Bad')",
@@ -40,6 +39,10 @@ class AddSubscribeInput(BaseModel):
         None,
         description="Douban ID for precise media identification (optional, alternative to tmdb_id)",
     )
+    bangumi_id: Optional[int] = Field(None, description="Bangumi media ID")
+    anilist_id: Optional[int] = Field(None, description="AniList media ID")
+    media_source: Optional[str] = Field(None, description="Media metadata source")
+    media_id: Optional[str] = Field(None, description="Native ID for media_source")
     start_episode: Optional[int] = Field(
         None,
         description="Starting episode number for TV shows (optional, defaults to 1 if not specified)",
@@ -72,6 +75,11 @@ class AddSubscribeInput(BaseModel):
 
 class AddSubscribeTool(MoviePilotTool):
     name: str = "add_subscribe"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.Subscription,
+        ToolTag.Media,
+    ]
     description: str = (
         "Add media subscription to create automated download rules for movies and TV shows. "
         "The system will automatically search and download new episodes or releases based on the subscription criteria. "
@@ -93,7 +101,7 @@ class AddSubscribeTool(MoviePilotTool):
             message += f" ({year})"
         if media_type:
             message += f" [{media_type}]"
-        if season:
+        if season is not None:
             message += f" 第{season}季"
         elif media_type == "tv":
             message += " 第1季(默认)"
@@ -140,6 +148,10 @@ class AddSubscribeTool(MoviePilotTool):
         season: Optional[int] = None,
         tmdb_id: Optional[int] = None,
         douban_id: Optional[str] = None,
+        bangumi_id: Optional[int] = None,
+        anilist_id: Optional[int] = None,
+        media_source: Optional[str] = None,
+        media_id: Optional[str] = None,
         start_episode: Optional[int] = None,
         total_episode: Optional[int] = None,
         quality: Optional[str] = None,
@@ -193,6 +205,10 @@ class AddSubscribeTool(MoviePilotTool):
                 year=year,
                 tmdbid=tmdb_id,
                 doubanid=douban_id,
+                bangumiid=bangumi_id,
+                anilistid=anilist_id,
+                media_source=media_source,
+                media_id=media_id,
                 season=season,
                 username=subscribe_username,
                 **subscribe_kwargs,

app/agent/tools/impl/ask_user_choice.py

@@ -4,7 +4,8 @@ from typing import List, Optional, Type
 
 from pydantic import BaseModel, Field, model_validator
 
-from app.agent.tools.base import MoviePilotTool, ToolChain
+from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.helper.interaction import (
     AgentInteractionOption,
     agent_interaction_manager,
@@ -26,6 +27,7 @@ class UserChoiceOptionInput(BaseModel):
 
     @model_validator(mode="after")
     def validate_option(self):
+        """校验按钮选项的文案和值不能为空。"""
         label = str(self.label)
         value = str(self.value)
         if not label.strip():
@@ -38,8 +40,6 @@ class UserChoiceOptionInput(BaseModel):
 class AskUserChoiceInput(BaseModel):
     """按钮选择工具输入。"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why the agent needs the user to choose from buttons",)
     message: str = Field(
         ...,
         description="Question or prompt shown to the user together with the buttons",
@@ -55,6 +55,7 @@ class AskUserChoiceInput(BaseModel):
 
     @model_validator(mode="after")
     def validate_payload(self):
+        """校验按钮选择工具必须提供问题和选项。"""
         message = str(self.message)
         if not message.strip():
             raise ValueError("message 不能为空")
@@ -67,16 +68,24 @@ class AskUserChoiceTool(MoviePilotTool):
     """发送按钮选择并让当前 Agent 轮次等待用户回调消息。"""
 
     name: str = "ask_user_choice"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.Message,
+        ToolTag.UserInteraction,
+        ToolTag.TerminalResponse,
+    ]
     sends_message: bool = True
     return_direct: bool = True
     description: str = (
         "Ask the user to choose from button options on channels that support interactive buttons. "
-        "After the user clicks a button, the selected value will come back as the user's next message."
+        "This is a terminal interaction tool: put the full question and all options in this call, "
+        "then stop the current turn. After the user clicks a button, the selected value will come "
+        "back as the user's next message. Do not also send the same question as plain text."
     )
     args_schema: Type[BaseModel] = AskUserChoiceInput
-    require_admin: bool = False
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
+        """生成工具执行提示文案。"""
         message = kwargs.get("message", "") or ""
         if len(message) > 40:
             message = message[:40] + "..."
@@ -84,6 +93,7 @@ class AskUserChoiceTool(MoviePilotTool):
 
     @staticmethod
     def _truncate_button_text(text: str, max_length: int) -> str:
+        """按渠道限制截断按钮文案。"""
         if max_length <= 0 or len(text) <= max_length:
             return text
         if max_length <= 3:
@@ -106,6 +116,14 @@ class AskUserChoiceTool(MoviePilotTool):
         title: Optional[str] = None,
         **kwargs,
     ) -> str:
+        """
+        发送按钮选择消息，并登记待回调的交互上下文。
+
+        :param message: 展示给用户的问题
+        :param options: 可点击的选项列表
+        :param title: 可选标题
+        :return: 工具执行结果描述
+        """
         if self._blocked_by_feedback_quality_gate():
             logger.warning(
                 "ask_user_choice blocked after feedback issue rejected_quality: "
@@ -140,7 +158,8 @@ class AskUserChoiceTool(MoviePilotTool):
 
         choice_options = [
             AgentInteractionOption(
-                label=option.label.strip(), value=option.value.strip()
+                label=option.label.strip(),
+                value=option.value.strip(),
             )
             for option in options
         ]
@@ -180,7 +199,7 @@ class AskUserChoiceTool(MoviePilotTool):
             len(choice_options),
         )
 
-        await ToolChain().async_post_message(
+        await self.send_notification_message(
             Notification(
                 channel=channel,
                 source=self._source,
@@ -190,6 +209,7 @@ class AskUserChoiceTool(MoviePilotTool):
                 title=title,
                 text=message.strip(),
                 buttons=buttons,
+                save_history=False,
             )
         )
 

app/agent/tools/impl/browse_webpage.py

@@ -1,19 +1,19 @@
 """浏览器操作工具 - 让Agent能够通过Playwright控制浏览器进行网页交互"""
 
-import asyncio
 import base64
 import json
 from enum import Enum
-from typing import Optional, Type
+from typing import Any, Optional, Type
 
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
-from app.core.config import settings
+from app.agent.tools.tags import ToolTag
+from app.helper.browser import BrowserSessionHelper
 from app.log import logger
 
-# 页面内容最大长度
-MAX_CONTENT_LENGTH = 8000
+# 页面内容最大长度；保留在全局工具结果兜底上限以内。
+MAX_CONTENT_LENGTH = 12_000
 # 默认超时时间（秒）
 DEFAULT_TIMEOUT = 30
 # 截图最大宽度
@@ -26,32 +26,48 @@ class BrowserAction(str, Enum):
     """浏览器操作类型"""
 
     GOTO = "goto"
+    SNAPSHOT = "snapshot"
     GET_CONTENT = "get_content"
     SCREENSHOT = "screenshot"
     CLICK = "click"
+    CLICK_REF = "click_ref"
     FILL = "fill"
+    FILL_REF = "fill_ref"
     SELECT = "select"
+    SELECT_REF = "select_ref"
     EVALUATE = "evaluate"
     WAIT = "wait"
+    LIST_TABS = "list_tabs"
+    OPEN_TAB = "open_tab"
+    FOCUS_TAB = "focus_tab"
+    CLOSE_TAB = "close_tab"
+    CLOSE_SESSION = "close_session"
 
 
 class BrowseWebpageInput(BaseModel):
     """浏览器操作工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        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"
+            "- 'snapshot': Get current page snapshot with interactive element refs\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"
+            "- 'click_ref': Click an element by ref from the latest snapshot\n"
             "- 'fill': Fill text into an input element specified by selector\n"
+            "- 'fill_ref': Fill text into an input element by ref from the latest snapshot\n"
             "- 'select': Select an option from a dropdown element\n"
+            "- 'select_ref': Select an option by ref from the latest snapshot\n"
             "- 'evaluate': Execute JavaScript code on the page and return the result\n"
-            "- 'wait': Wait for an element to appear on the page"
+            "- 'wait': Wait for an element to appear on the page\n"
+            "- 'list_tabs': List browser tabs in the current session\n"
+            "- 'open_tab': Open a new tab, optionally navigating to a URL\n"
+            "- 'focus_tab': Switch active tab by index\n"
+            "- 'close_tab': Close a tab by index\n"
+            "- 'close_session': Close the current browser session"
         ),
     )
     url: Optional[str] = Field(
@@ -62,6 +78,10 @@ class BrowseWebpageInput(BaseModel):
         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'",
     )
+    ref: Optional[str] = Field(
+        None,
+        description="Element ref returned by 'snapshot' or action results (for 'click_ref', 'fill_ref', 'select_ref')",
+    )
     value: Optional[str] = Field(
         None,
         description="Value to fill into input or option value to select (for 'fill' and 'select' actions)",
@@ -85,18 +105,36 @@ class BrowseWebpageInput(BaseModel):
     user_agent: Optional[str] = Field(
         None, description="Custom User-Agent string for the browser context"
     )
+    session_key: Optional[str] = Field(
+        None,
+        description="Browser session key. Defaults to the current agent session id.",
+    )
+    tab_index: Optional[int] = Field(
+        None,
+        description="Tab index for 'focus_tab' and 'close_tab' actions.",
+    )
+    allow_private_network: bool = Field(
+        False,
+        description="Allow browser navigation to localhost, loopback, private, or link-local addresses.",
+    )
 
 
 class BrowseWebpageTool(MoviePilotTool):
     name: str = "browse_webpage"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Web,
+    ]
     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. "
+        "clicking elements, filling forms, selecting dropdown options, executing JavaScript, waiting for elements, "
+        "and managing tabs. "
         "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."
+        "first call 'goto' to open a page, inspect 'interactive_elements', then use *_ref actions when possible. "
+        "For safety, localhost and private network URLs are blocked by default unless allow_private_network is true."
     )
     args_schema: Type[BaseModel] = BrowseWebpageInput
 
@@ -107,13 +145,22 @@ class BrowseWebpageTool(MoviePilotTool):
         selector = kwargs.get("selector", "")
         action_messages = {
             "goto": f"打开网页: {url}",
+            "snapshot": "读取页面快照",
             "get_content": "获取页面内容",
             "screenshot": "截取页面截图",
             "click": f"点击元素: {selector}",
+            "click_ref": f"点击元素引用: {kwargs.get('ref', '')}",
             "fill": f"填写表单: {selector}",
+            "fill_ref": f"填写元素引用: {kwargs.get('ref', '')}",
             "select": f"选择选项: {selector}",
+            "select_ref": f"选择元素引用: {kwargs.get('ref', '')}",
             "evaluate": "执行 JavaScript",
             "wait": f"等待元素: {selector}",
+            "list_tabs": "列出浏览器标签页",
+            "open_tab": f"打开新标签页: {url}",
+            "focus_tab": f"切换浏览器标签页: {kwargs.get('tab_index', '')}",
+            "close_tab": f"关闭浏览器标签页: {kwargs.get('tab_index', '')}",
+            "close_session": "关闭浏览器会话",
         }
         return action_messages.get(action, f"执行浏览器操作: {action}")
 
@@ -122,12 +169,16 @@ class BrowseWebpageTool(MoviePilotTool):
         action: str,
         url: Optional[str] = None,
         selector: Optional[str] = None,
+        ref: 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,
+        session_key: Optional[str] = None,
+        tab_index: Optional[int] = None,
+        allow_private_network: bool = False,
         **kwargs,
     ) -> str:
         """执行浏览器操作"""
@@ -146,6 +197,8 @@ class BrowseWebpageTool(MoviePilotTool):
             # 参数校验
             if browser_action == BrowserAction.GOTO and not url:
                 return "错误: 'goto' 操作需要提供 url 参数"
+            if browser_action == BrowserAction.OPEN_TAB and not url:
+                return "错误: 'open_tab' 操作需要提供 url 参数"
             if (
                 browser_action
                 in (
@@ -157,26 +210,51 @@ class BrowseWebpageTool(MoviePilotTool):
                 and not selector
             ):
                 return f"错误: '{action}' 操作需要提供 selector 参数"
+            if (
+                browser_action
+                in (
+                    BrowserAction.CLICK_REF,
+                    BrowserAction.FILL_REF,
+                    BrowserAction.SELECT_REF,
+                )
+                and not ref
+            ):
+                return f"错误: '{action}' 操作需要提供 ref 参数"
             if browser_action == BrowserAction.FILL and value is None:
                 return "错误: 'fill' 操作需要提供 value 参数"
+            if browser_action == BrowserAction.FILL_REF and value is None:
+                return "错误: 'fill_ref' 操作需要提供 value 参数"
             if browser_action == BrowserAction.EVALUATE and not script:
                 return "错误: 'evaluate' 操作需要提供 script 参数"
+            if (
+                browser_action == BrowserAction.EVALUATE
+                and not await self.is_admin_user()
+            ):
+                return "错误: 'evaluate' 操作仅允许管理员使用"
+            if (
+                browser_action in (BrowserAction.FOCUS_TAB, BrowserAction.CLOSE_TAB)
+                and tab_index is None
+            ):
+                return f"错误: '{action}' 操作需要提供 tab_index 参数"
 
-            # 在线程池中运行同步的 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,
-                ),
+            effective_session_key = session_key or self._session_id
+
+            result = await self.run_blocking(
+                "web",
+                self._execute_browser_action,
+                browser_action=browser_action,
+                url=url,
+                selector=selector,
+                ref=ref,
+                value=value,
+                script=script,
+                content_type=content_type,
+                timeout=timeout,
+                cookies=cookies,
+                user_agent=user_agent,
+                session_key=effective_session_key,
+                tab_index=tab_index,
+                allow_private_network=allow_private_network,
             )
             return result
 
@@ -189,65 +267,61 @@ class BrowseWebpageTool(MoviePilotTool):
         browser_action: BrowserAction,
         url: Optional[str],
         selector: Optional[str],
+        ref: Optional[str],
         value: Optional[str],
         script: Optional[str],
         content_type: Optional[str],
         timeout: int,
         cookies: Optional[str],
         user_agent: Optional[str],
+        session_key: str,
+        tab_index: Optional[int],
+        allow_private_network: bool,
     ) -> str:
         """在同步上下文中执行 CloakBrowser 浏览器操作"""
-        from cloakbrowser import launch_context
 
         try:
-            context = None
-            page = None
-            try:
-                context_kwargs = {
-                    "viewport": {
-                        "width": SCREENSHOT_MAX_WIDTH,
-                        "height": SCREENSHOT_MAX_HEIGHT,
+            if browser_action == BrowserAction.CLOSE_SESSION:
+                closed = BrowserSessionHelper.close_session(session_key)
+                message = "浏览器会话已关闭" if closed else "浏览器会话不存在"
+                return self._json_response(
+                    {
+                        "success": closed,
+                        "message": message,
                     }
-                }
-                if user_agent:
-                    context_kwargs["user_agent"] = user_agent
-
-                context = launch_context(
-                    headless=True,
-                    humanize=settings.CLOAKBROWSER_HUMANIZE,
-                    human_preset=settings.CLOAKBROWSER_HUMAN_PRESET,
-                    **context_kwargs,
                 )
-                page = context.new_page()
-                page.set_default_timeout(timeout * 1000)
 
-                # 设置 cookies
-                if cookies:
-                    page.set_extra_http_headers({"cookie": cookies})
+            helper = BrowserSessionHelper(
+                headless=True,
+                viewport={
+                    "width": SCREENSHOT_MAX_WIDTH,
+                    "height": SCREENSHOT_MAX_HEIGHT,
+                },
+            )
 
-                # 对于非 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,
+            def _callback(session) -> str:
+                return self._do_action(
+                    helper=helper,
+                    session=session,
+                    browser_action=browser_action,
+                    url=url,
+                    selector=selector,
+                    ref=ref,
+                    value=value,
+                    script=script,
+                    content_type=content_type,
+                    timeout=timeout,
+                    tab_index=tab_index,
+                    allow_private_network=allow_private_network,
                 )
-                return result
 
-            finally:
-                if page:
-                    page.close()
-                if context:
-                    context.close()
+            return helper.with_session(
+                session_key=session_key,
+                callback=_callback,
+                user_agent=user_agent,
+                cookies=cookies,
+                timeout=timeout,
+            )
 
         except Exception as e:
             logger.error(f"CloakBrowser 执行失败: {e}", exc_info=True)
@@ -255,19 +329,38 @@ class BrowseWebpageTool(MoviePilotTool):
 
     def _do_action(
         self,
-        page,
+        helper: BrowserSessionHelper,
+        session,
         browser_action: BrowserAction,
         url: Optional[str],
         selector: Optional[str],
+        ref: Optional[str],
         value: Optional[str],
         script: Optional[str],
         content_type: Optional[str],
         timeout: int,
+        tab_index: Optional[int],
+        allow_private_network: bool,
     ) -> str:
         """执行具体的浏览器操作"""
+        page = session.active_page
 
         if browser_action == BrowserAction.GOTO:
-            return self._action_goto(page, url, timeout)
+            return self._action_goto(
+                helper,
+                page,
+                url,
+                timeout,
+                allow_private_network=allow_private_network,
+            )
+
+        elif browser_action == BrowserAction.SNAPSHOT:
+            return self._json_response(
+                BrowserSessionHelper.build_snapshot(
+                    page,
+                    max_text_chars=MAX_CONTENT_LENGTH,
+                )
+            )
 
         elif browser_action == BrowserAction.GET_CONTENT:
             return self._action_get_content(page, content_type)
@@ -278,89 +371,113 @@ class BrowseWebpageTool(MoviePilotTool):
         elif browser_action == BrowserAction.CLICK:
             return self._action_click(page, selector, timeout)
 
+        elif browser_action == BrowserAction.CLICK_REF:
+            return self._action_click(
+                page,
+                BrowserSessionHelper.ref_to_selector(ref),
+                timeout,
+                ref=ref,
+            )
+
         elif browser_action == BrowserAction.FILL:
             return self._action_fill(page, selector, value, timeout)
 
+        elif browser_action == BrowserAction.FILL_REF:
+            return self._action_fill(
+                page,
+                BrowserSessionHelper.ref_to_selector(ref),
+                value,
+                timeout,
+                ref=ref,
+            )
+
         elif browser_action == BrowserAction.SELECT:
             return self._action_select(page, selector, value, timeout)
 
+        elif browser_action == BrowserAction.SELECT_REF:
+            return self._action_select(
+                page,
+                BrowserSessionHelper.ref_to_selector(ref),
+                value,
+                timeout,
+                ref=ref,
+            )
+
         elif browser_action == BrowserAction.EVALUATE:
             return self._action_evaluate(page, script)
 
         elif browser_action == BrowserAction.WAIT:
             return self._action_wait(page, selector, timeout)
 
+        elif browser_action == BrowserAction.LIST_TABS:
+            return self._json_response({"tabs": BrowserSessionHelper.list_tabs(session)})
+
+        elif browser_action == BrowserAction.OPEN_TAB:
+            page = helper.open_tab(
+                session,
+                url=url,
+                timeout=timeout,
+                allow_private_network=allow_private_network,
+            )
+            return self._json_response(
+                {
+                    "success": True,
+                    "active_tab": session.active_index,
+                    "tabs": BrowserSessionHelper.list_tabs(session),
+                    "snapshot": BrowserSessionHelper.build_snapshot(
+                        page,
+                        max_text_chars=MAX_CONTENT_LENGTH,
+                    ),
+                }
+            )
+
+        elif browser_action == BrowserAction.FOCUS_TAB:
+            page = BrowserSessionHelper.focus_tab(session, tab_index)
+            return self._json_response(
+                {
+                    "success": True,
+                    "active_tab": session.active_index,
+                    "tabs": BrowserSessionHelper.list_tabs(session),
+                    "snapshot": BrowserSessionHelper.build_snapshot(
+                        page,
+                        max_text_chars=MAX_CONTENT_LENGTH,
+                    ),
+                }
+            )
+
+        elif browser_action == BrowserAction.CLOSE_TAB:
+            tabs = BrowserSessionHelper.close_tab(session, tab_index)
+            return self._json_response({"success": True, "tabs": tabs})
+
         return f"未知操作: {browser_action}"
 
     @staticmethod
-    def _action_goto(page, url: str, timeout: int) -> str:
+    def _json_response(payload: dict[str, Any]) -> str:
+        """返回格式化 JSON 字符串"""
+        return json.dumps(payload, ensure_ascii=False, indent=2)
+
+    @staticmethod
+    def _action_goto(
+        helper: BrowserSessionHelper,
+        page,
+        url: str,
+        timeout: int,
+        allow_private_network: bool,
+    ) -> 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
-
+        response = helper.goto(
+            page,
+            url,
+            timeout=timeout,
+            allow_private_network=allow_private_network,
+        )
         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)
+        result = BrowserSessionHelper.build_snapshot(
+            page,
+            status=status,
+            max_text_chars=MAX_CONTENT_LENGTH,
+        )
+        return BrowseWebpageTool._json_response(result)
 
     @staticmethod
     def _action_get_content(page, content_type: Optional[str]) -> str:
@@ -382,7 +499,7 @@ class BrowseWebpageTool(MoviePilotTool):
             "content_type": content_type,
             "content": content,
         }
-        return json.dumps(result, ensure_ascii=False, indent=2)
+        return BrowseWebpageTool._json_response(result)
 
     @staticmethod
     def _action_screenshot(page) -> str:
@@ -415,10 +532,15 @@ class BrowseWebpageTool(MoviePilotTool):
             "format": "jpeg",
             "note": "截图已以 base64 编码返回",
         }
-        return json.dumps(result, ensure_ascii=False, indent=2)
+        return BrowseWebpageTool._json_response(result)
 
     @staticmethod
-    def _action_click(page, selector: str, timeout: int) -> str:
+    def _action_click(
+        page,
+        selector: str,
+        timeout: int,
+        ref: Optional[str] = None,
+    ) -> str:
         """点击元素"""
         page.click(selector, timeout=timeout * 1000)
 
@@ -428,49 +550,62 @@ class BrowseWebpageTool(MoviePilotTool):
         except Exception:
             pass
 
-        title = page.title()
-        page_url = page.url
-
-        return json.dumps(
+        return BrowseWebpageTool._json_response(
             {
                 "success": True,
-                "message": f"成功点击元素: {selector}",
-                "current_url": page_url,
-                "current_title": title,
-            },
-            ensure_ascii=False,
-            indent=2,
+                "message": f"成功点击元素: {ref or selector}",
+                "snapshot": BrowserSessionHelper.build_snapshot(
+                    page,
+                    max_text_chars=MAX_CONTENT_LENGTH,
+                ),
+            }
         )
 
     @staticmethod
-    def _action_fill(page, selector: str, value: str, timeout: int) -> str:
+    def _action_fill(
+        page,
+        selector: str,
+        value: str,
+        timeout: int,
+        ref: Optional[str] = None,
+    ) -> str:
         """填写表单"""
         page.fill(selector, value, timeout=timeout * 1000)
 
-        return json.dumps(
+        return BrowseWebpageTool._json_response(
             {
                 "success": True,
-                "message": f"成功填写元素 '{selector}' 的值为 '{value}'",
-            },
-            ensure_ascii=False,
-            indent=2,
+                "message": f"成功填写元素 '{ref or selector}'",
+                "snapshot": BrowserSessionHelper.build_snapshot(
+                    page,
+                    max_text_chars=MAX_CONTENT_LENGTH,
+                ),
+            }
         )
 
     @staticmethod
-    def _action_select(page, selector: str, value: Optional[str], timeout: int) -> str:
+    def _action_select(
+        page,
+        selector: str,
+        value: Optional[str],
+        timeout: int,
+        ref: Optional[str] = None,
+    ) -> str:
         """选择下拉选项"""
         if value:
             page.select_option(selector, value=value, timeout=timeout * 1000)
         else:
             return "错误: 'select' 操作需要提供 value 参数"
 
-        return json.dumps(
+        return BrowseWebpageTool._json_response(
             {
                 "success": True,
-                "message": f"成功选择元素 '{selector}' 的选项 '{value}'",
-            },
-            ensure_ascii=False,
-            indent=2,
+                "message": f"成功选择元素 '{ref or selector}' 的选项 '{value}'",
+                "snapshot": BrowserSessionHelper.build_snapshot(
+                    page,
+                    max_text_chars=MAX_CONTENT_LENGTH,
+                ),
+            }
         )
 
     @staticmethod
@@ -490,13 +625,11 @@ class BrowseWebpageTool(MoviePilotTool):
         if len(formatted) > MAX_CONTENT_LENGTH:
             formatted = formatted[:MAX_CONTENT_LENGTH] + "\n\n...(结果已截断)"
 
-        return json.dumps(
+        return BrowseWebpageTool._json_response(
             {
                 "success": True,
                 "result": formatted,
-            },
-            ensure_ascii=False,
-            indent=2,
+            }
         )
 
     @staticmethod
@@ -510,22 +643,22 @@ class BrowseWebpageTool(MoviePilotTool):
             if text and len(text) > 200:
                 text = text[:200] + "..."
 
-            return json.dumps(
+            return BrowseWebpageTool._json_response(
                 {
                     "success": True,
                     "message": f"元素 '{selector}' 已出现",
                     "visible": visible,
                     "text": text,
-                },
-                ensure_ascii=False,
-                indent=2,
+                    "snapshot": BrowserSessionHelper.build_snapshot(
+                        page,
+                        max_text_chars=MAX_CONTENT_LENGTH,
+                    ),
+                }
             )
         else:
-            return json.dumps(
+            return BrowseWebpageTool._json_response(
                 {
                     "success": False,
                     "message": f"等待元素 '{selector}' 超时",
-                },
-                ensure_ascii=False,
-                indent=2,
+                }
             )

app/agent/tools/impl/create_agent_task.py

@@ -0,0 +1,161 @@
+import json
+from datetime import datetime, timedelta
+from typing import Literal, Optional, Type
+
+import pytz
+from pydantic import BaseModel, Field, model_validator
+
+from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
+from app.core.config import settings
+from app.db.agentchat_oper import AgentChatOper
+from app.db.agenttask_oper import AgentTaskOper
+from app.utils.timer import TimerUtils
+
+
+class CreateAgentTaskInput(BaseModel):
+    """创建 Agent 自主定时任务的输入参数。"""
+
+    name: str = Field(
+        ...,
+        min_length=1,
+        max_length=100,
+        description="Short task name shown in task management and execution reports.",
+    )
+    content: str = Field(
+        ...,
+        min_length=1,
+        max_length=10000,
+        description="Complete instructions that the agent must execute when the task fires.",
+    )
+    trigger_type: Literal["date", "cron"] = Field(
+        ...,
+        description="Use 'date' for one exact future run or 'cron' for recurring work.",
+    )
+    trigger: Optional[str] = Field(
+        None,
+        min_length=1,
+        max_length=200,
+        description=(
+            "For date, an ISO 8601 local or timezone-aware time such as "
+            "2026-07-19 20:30:00; for cron, a standard five-field expression "
+            "(minute hour day month weekday). The MoviePilot system timezone is used."
+        ),
+    )
+    delay_minutes: Optional[int] = Field(
+        None,
+        ge=1,
+        le=525600,
+        description=(
+            "For a one-time date task expressed as 'in N minutes', provide this instead "
+            "of trigger. MoviePilot calculates and persists the exact future run time."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_trigger(self) -> "CreateAgentTaskInput":
+        """校验任务触发配置并统一格式。"""
+        self.name = self.name.strip()
+        self.content = self.content.strip()
+        if not self.name or not self.content:
+            raise ValueError("name 和 content 不能只包含空白字符")
+        if self.trigger_type == "date":
+            if self.delay_minutes is not None:
+                # LangChain 会在 run() 前后各校验一次，延迟时间在持久化前统一计算。
+                self.trigger = None
+                return self
+            if self.trigger is None:
+                raise ValueError("date 任务必须提供 trigger 或 delay_minutes")
+        elif self.trigger is None or self.delay_minutes is not None:
+            raise ValueError("cron 任务必须提供 trigger，且不能提供 delay_minutes")
+        self.trigger_type, self.trigger = TimerUtils.normalize_schedule_trigger(
+            trigger_type=self.trigger_type,
+            trigger_value=self.trigger,
+            timezone_name=settings.TZ,
+            require_future=True,
+        )
+        return self
+
+
+class CreateAgentTaskTool(MoviePilotTool):
+    """创建可精确唤醒当前 Agent 会话的自主定时任务。"""
+
+    name: str = "create_agent_task"
+    tags: list[str] = [ToolTag.Write, ToolTag.AgentTask, ToolTag.Admin]
+    description: str = (
+        "Create a persistent autonomous agent task only when the user explicitly asks "
+        "for delayed, scheduled, recurring, reminder, or monitoring work. Use trigger_type "
+        "'date' with delay_minutes for requests such as 'check in 30 minutes', an exact "
+        "trigger time for other one-time work, and 'cron' for recurring schedules. When "
+        "fired, MoviePilot wakes the agent in this conversation, executes content, and "
+        "broadcasts user-facing messages through the configured notification channels."
+    )
+    args_schema: Type[BaseModel] = CreateAgentTaskInput
+    require_admin: bool = True
+
+    def get_tool_message(self, **kwargs: object) -> Optional[str]:
+        """生成创建定时任务的提示消息。"""
+        return f"创建自主定时任务：{kwargs.get('name', '')}"
+
+    def _create_task(self, payload: CreateAgentTaskInput) -> dict:
+        """持久化任务并立即注册到运行时调度器。"""
+        from app.scheduler import Scheduler
+
+        trigger_value = payload.trigger
+        if payload.trigger_type == "date" and payload.delay_minutes is not None:
+            timezone = pytz.timezone(settings.TZ)
+            trigger_value = (
+                datetime.now(timezone) + timedelta(minutes=payload.delay_minutes)
+            ).isoformat(timespec="seconds")
+        _, trigger_value = TimerUtils.normalize_schedule_trigger(
+            trigger_type=payload.trigger_type,
+            trigger_value=trigger_value,
+            timezone_name=settings.TZ,
+            require_future=True,
+        )
+        chat = AgentChatOper().get(
+            session_id=self._session_id,
+            user_id=self._user_id,
+        )
+        task = AgentTaskOper().add(
+            name=payload.name.strip(),
+            content=payload.content.strip(),
+            trigger_type=payload.trigger_type,
+            cron_expression=trigger_value if payload.trigger_type == "cron" else None,
+            run_at=trigger_value if payload.trigger_type == "date" else None,
+            user_id=str(self._user_id),
+            username=self._username or (chat.username if chat else None),
+            session_id=str(self._session_id),
+            channel=self._channel or (chat.channel if chat else None),
+            source=self._source or (chat.source if chat else None),
+            original_chat_id=chat.original_chat_id if chat else None,
+        )
+        scheduler = Scheduler()
+        next_run_at = scheduler.update_agent_task_job(task.id)
+        return AgentTaskOper.to_dict(
+            task,
+            next_run_at=next_run_at,
+            timezone=settings.TZ,
+        )
+
+    async def run(
+            self,
+            name: str,
+            content: str,
+            trigger_type: str,
+            trigger: Optional[str] = None,
+            delay_minutes: Optional[int] = None,
+            **kwargs: object,
+    ) -> str:
+        """创建 Agent 自主定时任务。"""
+        if not settings.AI_AGENT_ENABLE:
+            return "AI Agent 未启用，无法创建自主定时任务"
+        payload = CreateAgentTaskInput(
+            name=name,
+            content=content,
+            trigger_type=trigger_type,
+            trigger=trigger,
+            delay_minutes=delay_minutes,
+        )
+        task = await self.run_blocking("db", self._create_task, payload)
+        return json.dumps(task, ensure_ascii=False, indent=2)

app/agent/tools/impl/delete_agent_task.py

@@ -0,0 +1,50 @@
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
+from app.db.agenttask_oper import AgentTaskOper
+
+
+class DeleteAgentTaskInput(BaseModel):
+    """删除 Agent 自主定时任务的输入参数。"""
+
+    task_id: int = Field(..., ge=1, description="ID of the task to permanently delete.")
+
+
+class DeleteAgentTaskTool(MoviePilotTool):
+    """永久删除 Agent 自主定时任务。"""
+
+    name: str = "delete_agent_task"
+    tags: list[str] = [ToolTag.Write, ToolTag.AgentTask, ToolTag.Admin]
+    description: str = (
+        "Permanently delete an autonomous agent task and remove its runtime schedule. "
+        "Use update_agent_task with enabled=false when the user only wants to pause it."
+    )
+    args_schema: Type[BaseModel] = DeleteAgentTaskInput
+    require_admin: bool = True
+
+    def get_tool_message(self, **kwargs: object) -> Optional[str]:
+        """生成删除定时任务的提示消息。"""
+        return f"删除自主定时任务：{kwargs.get('task_id', '')}"
+
+    def _delete_task(self, task_id: int) -> bool:
+        """删除当前用户的任务并移除运行时调度。"""
+        from app.scheduler import Scheduler
+
+        deleted = AgentTaskOper().delete(
+            task_id=task_id,
+            user_id=str(self._user_id),
+        )
+        if deleted:
+            Scheduler().remove_agent_task_job(task_id)
+        return deleted
+
+    async def run(self, task_id: int, **kwargs: object) -> str:
+        """删除 Agent 自主定时任务。"""
+        payload = DeleteAgentTaskInput(task_id=task_id)
+        deleted = await self.run_blocking("db", self._delete_task, payload.task_id)
+        if not deleted:
+            return f"Agent 定时任务 {task_id} 不存在或不属于当前用户"
+        return f"Agent 定时任务 {task_id} 已删除"

app/agent/tools/impl/delete_custom_filter_rule.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._filter_rule_utils import (
     collect_custom_rule_group_refs,
     get_custom_rules,
@@ -19,13 +20,16 @@ from app.schemas.types import SystemConfigKey
 class DeleteCustomFilterRuleInput(BaseModel):
     """删除自定义过滤规则工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     rule_id: str = Field(..., description="Custom rule ID to delete.")
 
 
 class DeleteCustomFilterRuleTool(MoviePilotTool):
     name: str = "delete_custom_filter_rule"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.FilterRule,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Delete a custom filter rule from CustomFilterRules. "
         "If the rule is still referenced by rule groups, the deletion is blocked to avoid breaking rule_string expressions."

app/agent/tools/impl/delete_download_history.py

@@ -5,16 +5,14 @@ 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.agent.tools.tags import ToolTag
+from app.db.downloadhistory_oper import DownloadHistoryOper
 from app.log import logger
 
 
 class DeleteDownloadHistoryInput(BaseModel):
     """删除下载历史记录工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        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"
     )
@@ -22,6 +20,11 @@ class DeleteDownloadHistoryInput(BaseModel):
 
 class DeleteDownloadHistoryTool(MoviePilotTool):
     name: str = "delete_download_history"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.Download,
+        ToolTag.Admin,
+    ]
     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
     require_admin: bool = True
@@ -34,9 +37,8 @@ class DeleteDownloadHistoryTool(MoviePilotTool):
         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} 已成功删除"
+            await DownloadHistoryOper().async_delete_history(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/delete_download_tasks.py

@@ -5,15 +5,14 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.download import DownloadChain
 from app.log import logger
 
 
-class DeleteDownloadInput(BaseModel):
+class DeleteDownloadTasksInput(BaseModel):
     """删除下载任务工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        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)"
     )
@@ -27,10 +26,17 @@ class DeleteDownloadInput(BaseModel):
     )
 
 
-class DeleteDownloadTool(MoviePilotTool):
-    name: str = "delete_download"
+class DeleteDownloadTasksTool(MoviePilotTool):
+    """删除下载任务工具"""
+
+    name: str = "delete_download_tasks"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.Download,
+        ToolTag.Admin,
+    ]
     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
+    args_schema: Type[BaseModel] = DeleteDownloadTasksInput
     require_admin: bool = True
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
@@ -63,6 +69,7 @@ class DeleteDownloadTool(MoviePilotTool):
         delete_files: Optional[bool] = False,
         **kwargs,
     ) -> str:
+        """执行删除下载任务。"""
         logger.info(
             f"执行工具: {self.name}, 参数: hash={hash}, downloader={downloader}, delete_files={delete_files}"
         )

app/agent/tools/impl/delete_rule_group.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._filter_rule_utils import (
     get_rule_groups,
     remove_rule_group_references,
@@ -18,13 +19,16 @@ from app.schemas.types import SystemConfigKey
 class DeleteRuleGroupInput(BaseModel):
     """删除过滤规则组工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     name: str = Field(..., description="Rule group name to delete.")
 
 
 class DeleteRuleGroupTool(MoviePilotTool):
     name: str = "delete_rule_group"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.FilterRule,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Delete a filter rule group from UserFilterRuleGroups. "
         "The tool also removes dangling references from global settings and subscriptions."

app/agent/tools/impl/delete_subscribe.py

@@ -5,9 +5,10 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.core.event import eventmanager
 from app.db.subscribe_oper import SubscribeOper
-from app.helper.subscribe import SubscribeHelper
+from app.helper.server import MoviePilotServerHelper
 from app.log import logger
 from app.schemas.types import EventType
 
@@ -15,8 +16,6 @@ from app.schemas.types import EventType
 class DeleteSubscribeInput(BaseModel):
     """删除订阅工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        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 delete (can be obtained from query_subscribes tool)",
@@ -25,6 +24,11 @@ class DeleteSubscribeInput(BaseModel):
 
 class DeleteSubscribeTool(MoviePilotTool):
     name: str = "delete_subscribe"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.Subscription,
+        ToolTag.Admin,
+    ]
     description: str = "Delete a media subscription by its ID. This will remove the subscription and stop automatic downloads for that media."
     args_schema: Type[BaseModel] = DeleteSubscribeInput
     require_admin: bool = True
@@ -49,8 +53,16 @@ class DeleteSubscribeTool(MoviePilotTool):
 
             await subscribe_oper.async_delete(subscribe_id)
             # 分享订阅统计刷新本身已异步化，这里只需要在删除后触发即可。
-            SubscribeHelper().sub_done_async(
-                {"tmdbid": subscribe.tmdbid, "doubanid": subscribe.doubanid}
+            MoviePilotServerHelper.sub_done_async(
+                {
+                    "tmdbid": subscribe.tmdbid,
+                    "doubanid": subscribe.doubanid,
+                    "bangumiid": subscribe.bangumiid,
+                    "anilistid": subscribe.anilistid,
+                    "media_source": subscribe.media_source,
+                    "media_id": subscribe.media_id,
+                    "season": subscribe.season,
+                }
             )
 
             # 发送事件

app/agent/tools/impl/delete_transfer_history.py

@@ -5,15 +5,16 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
+from app.chain.storage import StorageChain
 from app.db.transferhistory_oper import TransferHistoryOper
 from app.log import logger
+from app.schemas import FileItem
 
 
 class DeleteTransferHistoryInput(BaseModel):
     """删除整理历史记录工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     history_id: int = Field(
         ..., description="The ID of the transfer history record to delete"
     )
@@ -21,7 +22,16 @@ class DeleteTransferHistoryInput(BaseModel):
 
 class DeleteTransferHistoryTool(MoviePilotTool):
     name: str = "delete_transfer_history"
-    description: str = "Delete a specific transfer history record by its ID. This is useful when you need to remove a failed transfer record before retrying the transfer, as the system skips files that already have transfer history."
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.Transfer,
+        ToolTag.Admin,
+    ]
+    description: str = (
+        "Delete a specific transfer history record by its ID. For non-successful-move records with an old "
+        "destination file, the tool removes that media-library file before deleting the history record. This is "
+        "useful before retrying or re-organizing because the system skips files that already have transfer history."
+    )
     args_schema: Type[BaseModel] = DeleteTransferHistoryInput
     require_admin: bool = True
 
@@ -42,10 +52,21 @@ class DeleteTransferHistoryTool(MoviePilotTool):
             title = history.title or "未知"
             src = history.src or "未知"
             status = "成功" if history.status else "失败"
+            deleted_dest = False
+            if history.dest_fileitem and not (history.status and history.mode == "move"):
+                dest_fileitem = FileItem(**history.dest_fileitem)
+                storage_chain = StorageChain()
+                if storage_chain.exists(dest_fileitem):
+                    if not storage_chain.delete_media_file(dest_fileitem):
+                        return f"错误：旧媒体库文件删除失败，路径={dest_fileitem.path}"
+                    deleted_dest = True
             await transferhis.async_delete(history_id)
-            return (
+            message = (
                 f"已删除整理历史记录：ID={history_id}，标题={title}，源路径={src}，状态={status}"
             )
+            if deleted_dest:
+                message += "，已删除旧媒体库文件"
+            return message
         except Exception as e:
             logger.error(f"删除整理历史记录失败: {e}", exc_info=True)
             return f"删除整理历史记录时发生错误: {str(e)}"

app/agent/tools/impl/edit_file.py

@@ -1,4 +1,4 @@
-"""文件编辑工具"""
+"""文件精确编辑工具。"""
 
 from pathlib import Path
 from typing import Optional, Type
@@ -7,22 +7,61 @@ from anyio import Path as AsyncPath
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.impl._file_write_utils import (
+    FileVersionConflictError,
+    atomic_write_text,
+    calculate_file_sha256,
+)
+from app.agent.tools.tags import ToolTag
 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")
+    old_text: str = Field(
+        ...,
+        description=(
+            "The exact old text to replace. It must be non-empty and uniquely "
+            "identify one location unless replace_all is true."
+        ),
+    )
     new_text: str = Field(..., description="The new text to replace with")
+    replace_all: bool = Field(
+        False,
+        description=(
+            "Replace every exact match. Keep false for normal code edits so an "
+            "ambiguous match fails instead of changing multiple locations."
+        ),
+    )
+    expected_sha256: Optional[str] = Field(
+        None,
+        pattern=r"^[0-9a-fA-F]{64}$",
+        description=(
+            "Optional SHA-256 returned by read_file(include_metadata=true). The "
+            "edit fails if the file changed after it was read."
+        ),
+    )
 
 
 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."
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.File,
+    ]
+    description: str = (
+        "Edit an existing local text file using an exact text match. By default "
+        "the match must occur exactly once; use replace_all only for intentional "
+        "bulk replacement. old_text cannot be empty, and new files must be "
+        "created with write_file. Supports an optional SHA-256 conflict check. "
+        "Non-admin users can only edit files inside the MoviePilot Agent config "
+        "directory."
+    )
     args_schema: Type[BaseModel] = EditFileInput
-    require_admin: bool = True
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据参数生成友好的提示消息"""
@@ -30,41 +69,93 @@ class EditFileTool(MoviePilotTool):
         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:
+    async def run(
+        self,
+        file_path: str,
+        old_text: str,
+        new_text: str,
+        replace_all: bool = False,
+        expected_sha256: Optional[str] = None,
+        **kwargs,
+    ) -> str:
+        """校验精确匹配和可选文件版本后，以原子方式写入编辑结果。"""
         logger.info(f"执行工具: {self.name}, 参数: file_path={file_path}")
 
         try:
-            path = AsyncPath(file_path)
-            # 校验逻辑：如果要替换特定文本，文件必须存在且包含该文本
+            resolved_path, access_error = await self._check_local_file_access(
+                file_path, operation="编辑"
+            )
+            if access_error:
+                return access_error
+
+            if not old_text:
+                return "错误：old_text 不能为空；创建或完整写入文件请使用 write_file。"
+
+            path = AsyncPath(resolved_path)
             if not await path.exists():
-                # 如果 old_text 为空，可能用户想直接创建文件，但通常 edit_file 需要匹配旧内容
-                if old_text:
-                    return f"错误：文件 {file_path} 不存在，无法进行内容替换。"
+                return f"错误：文件 {resolved_path} 不存在；创建文件请使用 write_file。"
 
-            if await path.exists() and not await path.is_file():
-                return f"错误：{file_path} 不是一个文件"
+            if not await path.is_file():
+                return f"错误：{resolved_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
+            local_path = Path(resolved_path)
+            current_sha256 = await self.run_blocking(
+                "default", calculate_file_sha256, local_path
+            )
+            if (
+                expected_sha256
+                and current_sha256.casefold() != expected_sha256.casefold()
+            ):
+                return (
+                    f"错误：文件 {resolved_path} 已在读取后发生变化，拒绝覆盖。"
+                    "请重新读取文件并基于最新内容编辑。"
+                )
 
-            # 自动创建父目录
-            await path.parent.mkdir(parents=True, exist_ok=True)
+            content = await path.read_text(encoding="utf-8", errors="strict")
+            occurrences = content.count(old_text)
+            if occurrences == 0:
+                logger.warning(f"编辑文件 {resolved_path} 失败：未找到指定的旧文本块")
+                return (
+                    f"错误：在文件 {resolved_path} 中未找到指定的旧文本。"
+                    "请重新读取文件并确认空格、缩进和换行。"
+                )
+            if occurrences > 1 and not replace_all:
+                return (
+                    f"错误：old_text 在文件 {resolved_path} 中匹配到 {occurrences} 处，"
+                    "为避免误改已拒绝编辑。请提供更多上下文使其唯一，或明确设置 "
+                    "replace_all=true。"
+                )
 
-            # 写入文件
-            await path.write_text(new_content, encoding="utf-8")
+            replacement_count = occurrences if replace_all else 1
+            new_content = content.replace(
+                old_text,
+                new_text,
+                -1 if replace_all else 1,
+            )
+            await self.run_blocking(
+                "default",
+                atomic_write_text,
+                local_path,
+                new_content,
+                current_sha256,
+            )
+            new_sha256 = await self.run_blocking(
+                "default", calculate_file_sha256, local_path
+            )
 
-            logger.info(f"成功编辑文件 {file_path}，替换了 {occurrences} 处内容")
-            return f"成功编辑文件 {file_path} (替换了 {occurrences} 处匹配内容)"
+            logger.info(
+                f"成功编辑文件 {resolved_path}，替换了 {replacement_count} 处内容"
+            )
+            return (
+                f"成功编辑文件 {resolved_path}（替换了 {replacement_count} 处匹配内容，"
+                f"sha256={new_sha256}）"
+            )
 
+        except FileVersionConflictError:
+            return (
+                f"错误：文件 {file_path} 在编辑期间发生变化，拒绝覆盖。"
+                "请重新读取文件并再次编辑。"
+            )
         except PermissionError:
             return f"错误：没有访问/修改 {file_path} 的权限"
         except UnicodeDecodeError:

app/agent/tools/impl/execute_command.py

@@ -7,14 +7,17 @@ import json
 import os
 import signal
 import subprocess
+from collections import deque
 from dataclasses import dataclass, field
 from tempfile import NamedTemporaryFile
 from typing import Any, Literal, Optional, TextIO, Type
 
 from pydantic import BaseModel, Field
 
+from app.agent.tools.impl._command_safety import validate_command_safety
 from app.agent.tools.base import MoviePilotTool
-from app.agent.tools.impl.terminal_session import (
+from app.agent.tools.tags import ToolTag
+from app.agent.tools.impl._terminal_session import (
     TERMINAL_DEFAULT_READ_BYTES,
     TERMINAL_MAX_READ_BYTES,
     TERMINAL_WAIT_DEFAULT_MS,
@@ -25,28 +28,24 @@ from app.log import logger
 
 DEFAULT_TIMEOUT_SECONDS = 60
 MAX_TIMEOUT_SECONDS = 300
-MAX_OUTPUT_PREVIEW_BYTES = 10 * 1024
+MAX_OUTPUT_PREVIEW_BYTES = 32 * 1024
+MAX_OUTPUT_HEAD_BYTES = 16 * 1024
+MAX_OUTPUT_TAIL_BYTES = 16 * 1024
 READ_CHUNK_SIZE = 4096
 KILL_GRACE_SECONDS = 3
 COMMAND_CONCURRENCY_LIMIT = 2
-COMMAND_FORBIDDEN_KEYWORDS = (
-    ":(){ :|:& };:",
-    "dd if=/dev/zero",
-    "mkfs",
-    "reboot",
-    "shutdown",
-)
-
 _command_semaphore = asyncio.Semaphore(COMMAND_CONCURRENCY_LIMIT)
 
 
 @dataclass
 class _CommandOutput:
-    """保存前 10KB 预览，并在超限时将完整输出写入临时文件。"""
+    """保存命令头尾预览，并在超限时将完整输出写入临时文件。"""
 
     preview_limit_bytes: int
     preview_entries: list[tuple[str, str]] = field(default_factory=list)
+    tail_entries: deque[tuple[str, str]] = field(default_factory=deque)
     captured_bytes: int = 0
+    tail_bytes: int = 0
     preview_truncated: bool = False
     temp_file_path: Optional[str] = None
     temp_file_handle: Optional[TextIO] = None
@@ -57,7 +56,7 @@ class _CommandOutput:
         """按 UTF-8 字节数截断文本，避免截断后出现非法字符。"""
         if byte_limit <= 0:
             return ""
-        return text.encode("utf-8")[:byte_limit].decode("utf-8", errors="ignore")
+        return text.encode("utf-8")[:byte_limit].decode("utf-8", errors="replace")
 
     def _write_chunk(self, stream_name: str, text: str) -> None:
         """把输出分片按 stdout/stderr 分段写入临时文件。"""
@@ -99,10 +98,12 @@ class _CommandOutput:
         self.temp_file_handle = None
 
     def append(self, stream_name: str, text: str) -> None:
-        """追加一段输出，超出预览上限后只保留完整日志文件。"""
+        """追加一段输出，超出预览上限后保留头尾预览和完整日志文件。"""
         if not text:
             return
 
+        self._append_tail(stream_name, text)
+
         if self.temp_file_handle:
             self._write_chunk(stream_name, text)
             return
@@ -123,6 +124,60 @@ class _CommandOutput:
             self.preview_entries.append((stream_name, preview))
             self.captured_bytes += len(preview.encode("utf-8"))
 
+    def _append_tail(self, stream_name: str, text: str) -> None:
+        """维护固定字节大小的尾部输出，方便定位测试和构建失败信息。"""
+        self.tail_entries.append((stream_name, text))
+        self.tail_bytes += len(text.encode("utf-8"))
+        while self.tail_bytes > MAX_OUTPUT_TAIL_BYTES and self.tail_entries:
+            old_stream, old_text = self.tail_entries.popleft()
+            old_bytes = len(old_text.encode("utf-8"))
+            overflow = self.tail_bytes - MAX_OUTPUT_TAIL_BYTES
+            if old_bytes <= overflow:
+                self.tail_bytes -= old_bytes
+                continue
+            kept_text = old_text.encode("utf-8")[overflow:].decode(
+                "utf-8", errors="ignore"
+            )
+            kept_bytes = len(kept_text.encode("utf-8"))
+            self.tail_bytes -= old_bytes
+            if kept_text:
+                self.tail_entries.appendleft((old_stream, kept_text))
+                self.tail_bytes += kept_bytes
+
+    @staticmethod
+    def _format_entries(entries: list[tuple[str, str]]) -> str:
+        """按 stdout/stderr 切换插入可读的输出分段标题。"""
+        parts: list[str] = []
+        last_stream: Optional[str] = None
+        for stream_name, text in entries:
+            if stream_name != last_stream:
+                title = "标准输出" if stream_name == "stdout" else "错误输出"
+                parts.append(f"\n[{title}]\n")
+                last_stream = stream_name
+            parts.append(text)
+        return "".join(parts).strip()
+
+    @property
+    def combined_preview(self) -> str:
+        """返回完整输出或头尾组合预览。"""
+        if not self.preview_truncated:
+            return self._format_entries(self.preview_entries)
+
+        head_entries: list[tuple[str, str]] = []
+        remaining = MAX_OUTPUT_HEAD_BYTES
+        for stream_name, text in self.preview_entries:
+            if remaining <= 0:
+                break
+            clipped = self._clip_text_to_bytes(text, remaining)
+            if clipped:
+                head_entries.append((stream_name, clipped))
+                remaining -= len(clipped.encode("utf-8"))
+        head = self._format_entries(head_entries)
+        tail = self._format_entries(list(self.tail_entries))
+        return (
+            f"{head}\n\n...(中间输出已省略，完整内容在临时文件中)...\n\n{tail}"
+        ).strip()
+
     @property
     def stdout(self) -> str:
         """返回当前保留的 stdout 预览。"""
@@ -141,7 +196,6 @@ class _CommandOutput:
 class ExecuteCommandInput(BaseModel):
     """执行 Shell 命令工具的输入参数模型。"""
 
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this command action is needed")
     action: Optional[Literal["start", "read", "wait", "write", "kill", "run"]] = Field(
         "start",
         description=(
@@ -194,12 +248,24 @@ class ExecuteCommandInput(BaseModel):
         60,
         description="For action=run, max execution time in seconds.",
     )
+    confirm_dangerous: Optional[bool] = Field(
+        False,
+        description=(
+            "Explicit confirmation for high-risk commands such as recursive root deletion, "
+            "disk formatting, shutdown/reboot, or destructive permission changes."
+        ),
+    )
 
 
 class ExecuteCommandTool(MoviePilotTool):
     """统一执行和管理 Shell 命令的 Agent 工具。"""
 
     name: str = "execute_command"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Command,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Start and manage shell commands on the server. By default action=start "
         "launches a background session and immediately returns session_id/status/"
@@ -249,34 +315,9 @@ class ExecuteCommandTool(MoviePilotTool):
         return command
 
     @staticmethod
-    def _validate_command(command: str) -> None:
+    def _validate_command(command: str, *, confirmed: bool = False) -> None:
         """复用旧工具的基础危险命令过滤，避免明显破坏性命令进入 shell。"""
-        for keyword in COMMAND_FORBIDDEN_KEYWORDS:
-            if keyword in command:
-                raise ValueError(f"命令包含禁止使用的关键字 '{keyword}'")
-
-        # 检查是否使用了 rm -r/R 删除根目录或一级目录，防止误杀多级目录
-        import re
-        import os.path
-        tokens = re.split(r'\s+', command.strip())
-        if any(t == "rm" or t.endswith("/rm") for t in tokens):
-            has_r = False
-            for token in tokens:
-                if token.startswith("-") and ("r" in token or "R" in token):
-                    has_r = True
-                    break
-            
-            if has_r:
-                for token in tokens:
-                    # 提取可能包含目标路径的部分（去除重定向、管道、分号等末尾干扰）
-                    m = re.match(r'^([^;\|&><]+)', token)
-                    if m:
-                        clean_token = m.group(1).strip('"\'')
-                        # 仅对绝对路径进行一级目录限制
-                        if clean_token.startswith('/'):
-                            norm_path = os.path.normpath(clean_token)
-                            if re.match(r'^/[^/]*$', norm_path) or re.match(r'^/[^/]*/$', norm_path):
-                                raise ValueError(f"不允许使用 rm 命令删除根目录或一级目录: {clean_token}")
+        validate_command_safety(command, confirmed=confirmed)
 
     @staticmethod
     def _normalize_timeout(timeout: Optional[int]) -> tuple[int, Optional[str]]:
@@ -315,7 +356,7 @@ class ExecuteCommandTool(MoviePilotTool):
         stream_name: str,
         output: _CommandOutput,
     ) -> None:
-        """按块读取一次性命令输出，只把前 10KB 保留在返回结果中。"""
+        """按块读取一次性命令输出，保留 32KB 头尾预览。"""
         while True:
             chunk = await stream.read(READ_CHUNK_SIZE)
             if not chunk:
@@ -361,7 +402,7 @@ class ExecuteCommandTool(MoviePilotTool):
                 asyncio.shield(wait_task), timeout=KILL_GRACE_SECONDS
             )
         except asyncio.TimeoutError:
-            logger.warning("命令进程强制清理超时: pid=%s", process.pid)
+            logger.warning(f"命令进程强制清理超时: pid={process.pid}")
 
     @staticmethod
     async def _finish_reader_tasks(reader_tasks: list[asyncio.Task]) -> None:
@@ -376,7 +417,7 @@ class ExecuteCommandTool(MoviePilotTool):
             if isinstance(result, Exception) and not isinstance(
                 result, asyncio.CancelledError
             ):
-                logger.debug("命令输出读取任务异常: %s", result)
+                logger.debug(f"命令输出读取任务异常: {result}")
 
     @staticmethod
     def _format_run_result(
@@ -399,17 +440,16 @@ class ExecuteCommandTool(MoviePilotTool):
             file_note = "截至命令终止前的完整输出" if timed_out else "完整输出"
             result += (
                 "\n\n提示:\n"
-                f"命令输出超过 10KB，仅返回前 {MAX_OUTPUT_PREVIEW_BYTES} 字节内容。\n"
+                f"命令输出超过 {MAX_OUTPUT_PREVIEW_BYTES // 1024}KB，"
+                f"仅返回前后各 {MAX_OUTPUT_HEAD_BYTES // 1024}KB 预览。\n"
                 f"{file_note}已写入临时文件: {output.temp_file_path}\n"
                 "如需完整内容，请继续读取该文件。"
             )
-        if output.stdout:
-            result += f"\n\n标准输出:\n{output.stdout}"
-        if output.stderr:
-            result += f"\n\n错误输出:\n{output.stderr}"
+        if output.combined_preview:
+            result += f"\n\n命令输出预览:\n{output.combined_preview}"
         if output.preview_truncated:
-            result += "\n\n...(仅展示前 10KB 内容)"
-        if not output.stdout and not output.stderr:
+            result += "\n\n...(仅展示前后各 16KB 内容)"
+        if not output.combined_preview:
             result += "\n\n(无输出内容)"
         return result
 
@@ -419,9 +459,10 @@ class ExecuteCommandTool(MoviePilotTool):
         command: str,
         timeout: Optional[int],
         cwd: Optional[str] = None,
+        confirm_dangerous: bool = False,
     ) -> str:
         """按旧模式一次性执行命令，等待完成或超时后返回文本结果。"""
-        self._validate_command(command)
+        self._validate_command(command, confirmed=confirm_dangerous)
         normalized_timeout, timeout_note = self._normalize_timeout(timeout)
 
         async with _command_semaphore:
@@ -445,6 +486,9 @@ class ExecuteCommandTool(MoviePilotTool):
             except asyncio.TimeoutError:
                 timed_out = True
                 await self._cleanup_process(process, wait_task)
+            except asyncio.CancelledError:
+                await self._cleanup_process(process, wait_task)
+                raise
 
             try:
                 await self._finish_reader_tasks(reader_tasks)
@@ -473,27 +517,29 @@ class ExecuteCommandTool(MoviePilotTool):
         max_bytes: Optional[int] = TERMINAL_DEFAULT_READ_BYTES,
         timeout_ms: Optional[int] = TERMINAL_WAIT_DEFAULT_MS,
         timeout: Optional[int] = 60,
+        confirm_dangerous: Optional[bool] = False,
         **kwargs,
     ) -> str:
         """执行命令动作：默认后台启动，也支持读取、等待、写入、终止和一次性执行。"""
         normalized_action = (action or "start").strip().lower()
         logger.info(
-            "执行工具: %s, action=%s, command=%s, session_id=%s",
-            self.name,
-            normalized_action,
-            command,
-            session_id,
+            f"执行工具: {self.name}, action={normalized_action}, "
+            f"command={command}, session_id={session_id}"
         )
 
         try:
             if normalized_action == "start":
                 start_command = self._require_command(command)
-                self._validate_command(start_command)
+                self._validate_command(
+                    start_command,
+                    confirmed=bool(confirm_dangerous),
+                )
                 payload = await terminal_session_manager.start(
                     command=start_command,
                     cwd=cwd,
                     env=env,
                     use_pty=use_pty,
+                    confirm_dangerous=bool(confirm_dangerous),
                 )
                 return self._dump(payload)
 
@@ -533,9 +579,10 @@ class ExecuteCommandTool(MoviePilotTool):
                     command=self._require_command(command),
                     timeout=timeout,
                     cwd=cwd,
+                    confirm_dangerous=bool(confirm_dangerous),
                 )
 
             raise ValueError(f"不支持的 action: {action}")
         except Exception as err:
-            logger.error("执行命令 action 失败: %s", err, exc_info=True)
+            logger.error(f"执行命令 action 失败: {err}", exc_info=True)
             return self._dump({"error": str(err), "status": "error", "action": normalized_action})

app/agent/tools/impl/get_recommendations.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.recommend import RecommendChain
 from app.log import logger
 from app.schemas.types import MediaType, media_type_to_agent
@@ -14,8 +15,6 @@ from app.schemas.types import MediaType, media_type_to_agent
 class GetRecommendationsInput(BaseModel):
     """获取推荐工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     source: Optional[str] = Field(
         "tmdb_trending",
         description="Recommendation source: "
@@ -44,6 +43,11 @@ class GetRecommendationsInput(BaseModel):
 
 class GetRecommendationsTool(MoviePilotTool):
     name: str = "get_recommendations"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Media,
+        ToolTag.Recommendation,
+    ]
     description: str = "Get trending and popular media recommendations from various sources. Returns curated lists of popular movies, TV shows, and anime based on different criteria like trending, ratings, or calendar schedules. Supports pagination with 20 items per page."
     args_schema: Type[BaseModel] = GetRecommendationsInput
 
@@ -206,6 +210,10 @@ class GetRecommendationsTool(MoviePilotTool):
                         "tmdb_id": r.get("tmdb_id"),
                         "imdb_id": r.get("imdb_id"),
                         "douban_id": r.get("douban_id"),
+                        "bangumi_id": r.get("bangumi_id"),
+                        "anilist_id": r.get("anilist_id"),
+                        "media_source": r.get("source"),
+                        "media_id": r.get("media_id"),
                         "vote_average": r.get("vote_average"),
                         "poster_path": r.get("poster_path"),
                         "detail_link": r.get("detail_link"),

app/agent/tools/impl/get_search_results.py

@@ -7,6 +7,7 @@ from typing import List, Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.search import SearchChain
 from app.log import logger
 from ._torrent_search_utils import (
@@ -20,8 +21,6 @@ from ._torrent_search_utils import (
 class GetSearchResultsInput(BaseModel):
     """获取搜索结果工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        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")
@@ -35,6 +34,14 @@ class GetSearchResultsInput(BaseModel):
         None,
         description="Regular expression pattern to filter torrent titles (e.g., '4K|2160p|UHD', '1080p.*BluRay')",
     )
+    content_pattern: Optional[str] = Field(
+        None,
+        description="Regular expression pattern to filter torrent titles, descriptions, and labels (e.g., '特效字幕|国语|DIY')",
+    )
+    include_description: Optional[bool] = Field(
+        False,
+        description="Whether to include torrent descriptions in returned results",
+    )
     show_filter_options: Optional[bool] = Field(
         False,
         description="Whether to return only optional filter options for re-checking available conditions",
@@ -46,11 +53,18 @@ class GetSearchResultsInput(BaseModel):
 
 
 class GetSearchResultsTool(MoviePilotTool):
+    """获取并筛选最近一次种子搜索结果"""
+
     name: str = "get_search_results"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Resource,
+    ]
     description: str = "Get cached torrent search results from search_torrents with optional filters. Supports pagination with up to 50 results per page."
     args_schema: Type[BaseModel] = GetSearchResultsInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
+        """返回工具执行提示"""
         return "获取搜索结果"
 
     async def run(
@@ -63,13 +77,33 @@ class GetSearchResultsTool(MoviePilotTool):
         resolution: Optional[List[str]] = None,
         release_group: Optional[List[str]] = None,
         title_pattern: Optional[str] = None,
+        content_pattern: Optional[str] = None,
+        include_description: bool = False,
         show_filter_options: bool = False,
         page: Optional[int] = 1,
         **kwargs,
     ) -> str:
+        """
+        获取并筛选最近一次种子搜索结果
+
+        :param site: 站点名称筛选项
+        :param season: 季集筛选项
+        :param free_state: 促销状态筛选项
+        :param video_code: 视频编码筛选项
+        :param edition: 制作版本筛选项
+        :param resolution: 分辨率筛选项
+        :param release_group: 发布组筛选项
+        :param title_pattern: 仅匹配种子标题的正则表达式
+        :param content_pattern: 匹配种子标题、简介和标签的正则表达式
+        :param include_description: 是否在结果中返回种子简介
+        :param show_filter_options: 是否只返回可用筛选项
+        :param page: 分页页码
+        :param kwargs: 工具框架附加参数
+        :return: JSON 格式的搜索结果或错误提示
+        """
         page = max(1, page or 1)
         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}, page={page}"
+            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}, content_pattern={content_pattern}, include_description={include_description}, show_filter_options={show_filter_options}, page={page}"
         )
 
         try:
@@ -84,14 +118,22 @@ class GetSearchResultsTool(MoviePilotTool):
                 }
                 return json.dumps(payload, ensure_ascii=False, indent=2)
 
-            regex_pattern = None
+            title_regex_pattern = None
             if title_pattern:
                 try:
-                    regex_pattern = re.compile(title_pattern, re.IGNORECASE)
+                    title_regex_pattern = re.compile(title_pattern, re.IGNORECASE)
                 except re.error as e:
                     logger.warning(f"正则表达式编译失败: {title_pattern}, 错误: {e}")
                     return f"正则表达式格式错误: {str(e)}"
 
+            content_regex_pattern = None
+            if content_pattern:
+                try:
+                    content_regex_pattern = re.compile(content_pattern, re.IGNORECASE)
+                except re.error as e:
+                    logger.warning(f"正则表达式编译失败: {content_pattern}, 错误: {e}")
+                    return f"正则表达式格式错误: {str(e)}"
+
             filtered_items = filter_contexts(
                 items=items,
                 site=site,
@@ -102,14 +144,29 @@ class GetSearchResultsTool(MoviePilotTool):
                 resolution=resolution,
                 release_group=release_group,
             )
-            if regex_pattern:
+            if title_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)
+                    and title_regex_pattern.search(item.torrent_info.title)
                 ]
+            if content_regex_pattern:
+                content_filtered_items = []
+                for item in filtered_items:
+                    torrent_info = item.torrent_info
+                    if not torrent_info:
+                        continue
+                    content_values = [torrent_info.title, torrent_info.description]
+                    content_values.extend(torrent_info.labels or [])
+                    if any(
+                        content_regex_pattern.search(str(value))
+                        for value in content_values
+                        if value
+                    ):
+                        content_filtered_items.append(item)
+                filtered_items = content_filtered_items
             if not filtered_items:
                 return "没有符合筛选条件的搜索结果，请调整筛选条件"
 
@@ -132,7 +189,11 @@ class GetSearchResultsTool(MoviePilotTool):
                 return f"第 {page} 页没有数据，共 {total_count} 条结果，共 {(total_count + page_size - 1) // page_size} 页。"
 
             results = [
-                simplify_search_result(item, index)
+                simplify_search_result(
+                    item,
+                    index,
+                    include_description=include_description,
+                )
                 for item, index in zip(page_items, page_indices)
             ]
             total_pages = (total_count + page_size - 1) // page_size

app/agent/tools/impl/install_plugin.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._plugin_tool_utils import (
     get_plugin_snapshot,
     install_plugin_runtime,
@@ -18,8 +19,6 @@ from app.log import logger
 class InstallPluginInput(BaseModel):
     """安装插件工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="Exact plugin ID to install. Use query_market_plugins first to find the correct plugin_id.",
@@ -36,6 +35,11 @@ class InstallPluginInput(BaseModel):
 
 class InstallPluginTool(MoviePilotTool):
     name: str = "install_plugin"
+    tags: list[str] = [
+        ToolTag.Write,
+        ToolTag.Plugin,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Install a plugin by exact plugin_id from the plugin market or local plugin repositories. "
         "Use query_market_plugins first when you need filtering or discovery."

app/agent/tools/impl/list_directory.py

@@ -8,23 +8,54 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.storage import StorageChain
 from app.log import logger
 from app.schemas.file import FileItem
 from app.utils.string import StringUtils
 
 
+DEFAULT_DIRECTORY_PAGE_SIZE = 50
+MAX_DIRECTORY_PAGE_SIZE = 200
+
+
 class ListDirectoryInput(BaseModel):
     """查询文件系统目录内容工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     path: str = Field(..., description="Directory path to list contents (e.g., '/home/user/downloads' or 'C:/Downloads')")
     storage: Optional[str] = Field("local", description="Storage type (default: 'local' for local file system, can be 'smb', 'alist', etc.)")
     sort_by: Optional[str] = Field("name", description="Sort order: 'name' for alphabetical sorting, 'time' for modification time sorting (default: 'name')")
+    limit: Optional[int] = Field(
+        DEFAULT_DIRECTORY_PAGE_SIZE,
+        ge=1,
+        le=MAX_DIRECTORY_PAGE_SIZE,
+        description=(
+            f"Maximum items to return in this page (default: {DEFAULT_DIRECTORY_PAGE_SIZE}, "
+            f"maximum: {MAX_DIRECTORY_PAGE_SIZE})"
+        ),
+    )
+    offset: Optional[int] = Field(
+        0,
+        ge=0,
+        description="Number of sorted directory items to skip before this page",
+    )
 
 
 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_directory_settings' to query directory configuration settings."
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Directory,
+        ToolTag.File,
+    ]
+    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 "
+        f"times. Returns a page of up to {DEFAULT_DIRECTORY_PAGE_SIZE} items with total "
+        f"count and next offset; limit is capped at {MAX_DIRECTORY_PAGE_SIZE}. "
+        "Use 'query_directory_settings' to query directory configuration settings."
+    )
     args_schema: Type[BaseModel] = ListDirectoryInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
@@ -40,10 +71,14 @@ class ListDirectoryTool(MoviePilotTool):
 
     @staticmethod
     def _list_directory_sync(
-        path: str, storage: Optional[str] = "local", sort_by: Optional[str] = "name"
+        path: str,
+        storage: Optional[str] = "local",
+        sort_by: Optional[str] = "name",
+        limit: Optional[int] = DEFAULT_DIRECTORY_PAGE_SIZE,
+        offset: Optional[int] = 0,
     ) -> str:
         """
-        目录遍历可能触发本地磁盘或远程存储请求，统一放到线程池中执行。
+        目录遍历可能触发本地磁盘或远程存储请求，统一放到线程池中执行并分页返回。
         """
         if not path:
             return "错误：路径不能为空"
@@ -59,9 +94,6 @@ class ListDirectoryTool(MoviePilotTool):
 
         if file_list is None:
             return f"无法访问目录：{path}，请检查路径是否正确或存储是否可用"
-        if not file_list:
-            return f"目录 {path} 为空"
-
         if sort_by == "time":
             file_list.sort(key=lambda x: x.modify_time or 0, reverse=True)
         else:
@@ -73,7 +105,14 @@ class ListDirectoryTool(MoviePilotTool):
             )
 
         total_count = len(file_list)
-        limited_list = file_list[:20]
+        normalized_limit = max(
+            1,
+            min(int(limit or DEFAULT_DIRECTORY_PAGE_SIZE), MAX_DIRECTORY_PAGE_SIZE),
+        )
+        normalized_offset = max(0, int(offset or 0))
+        limited_list = file_list[
+            normalized_offset : normalized_offset + normalized_limit
+        ]
         simplified_items = []
         for item in limited_list:
             size_str = StringUtils.str_filesize(item.size) if item.size else None
@@ -97,21 +136,57 @@ class ListDirectoryTool(MoviePilotTool):
                 simplified["extension"] = item.extension
             simplified_items.append(simplified)
 
-        result_json = json.dumps(simplified_items, ensure_ascii=False, indent=2)
-        if total_count > 20:
-            return (
-                f"注意：目录中共有 {total_count} 个项目，为节省上下文空间，仅显示前 20 个项目。\n\n"
-                f"{result_json}"
-            )
-        return result_json
+        returned_count = len(simplified_items)
+        has_more = normalized_offset + returned_count < total_count
+        return json.dumps(
+            {
+                "items": simplified_items,
+                "total_count": total_count,
+                "returned_count": returned_count,
+                "limit": normalized_limit,
+                "offset": normalized_offset,
+                "has_more": has_more,
+                "next_offset": (
+                    normalized_offset + returned_count if has_more else None
+                ),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
 
     async def run(self, path: str, storage: Optional[str] = "local",
-                  sort_by: Optional[str] = "name", **kwargs) -> str:
+                  sort_by: Optional[str] = "name",
+                  limit: Optional[int] = DEFAULT_DIRECTORY_PAGE_SIZE,
+                  offset: Optional[int] = 0,
+                  **kwargs) -> str:
+        """
+        分页查询指定目录的文件和子目录。
+
+        :param path: 要查询的目录路径
+        :param storage: 存储类型，默认为本地存储
+        :param sort_by: 排序方式，支持名称或修改时间
+        :param limit: 当前页最大条数，最高不超过工具上限
+        :param offset: 当前页起始偏移量
+        :return: 包含项目列表和分页元数据的 JSON 字符串
+        """
         logger.info(f"执行工具: {self.name}, 参数: path={path}, storage={storage}, sort_by={sort_by}")
 
         try:
+            resolved_path, access_error = await self._check_local_storage_access(
+                path=path, storage=storage, operation="列出"
+            )
+            if access_error:
+                return access_error
+            if resolved_path:
+                path = str(resolved_path)
             return await self.run_blocking(
-                "storage", self._list_directory_sync, path, storage, sort_by
+                "storage",
+                self._list_directory_sync,
+                path,
+                storage,
+                sort_by,
+                limit,
+                offset,
             )
         except Exception as e:
             logger.error(f"查询目录内容失败: {e}", exc_info=True)

app/agent/tools/impl/list_slash_commands.py

@@ -6,18 +6,22 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.log import logger
 
 
 class ListSlashCommandsInput(BaseModel):
     """查询所有可用斜杠命令工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
 
 
 class ListSlashCommandsTool(MoviePilotTool):
     name: str = "list_slash_commands"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.SlashCommand,
+        ToolTag.Admin,
+    ]
     description: str = (
         "List all available slash commands in the system, including system preset commands "
         "(e.g. /cookiecloud, /sites, /subscribes, /downloading, /transfer, /restart, etc.) "

app/agent/tools/impl/mcp.py

@@ -0,0 +1,98 @@
+"""外部 MCP 工具适配器。"""
+
+import json
+from typing import Any, Optional
+
+from pydantic import PrivateAttr
+
+from app.agent.mcp import AgentMcpToolSpec, agent_mcp_manager
+from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
+
+
+class McpExternalTool(MoviePilotTool):
+    """将外部 MCP 工具包装为 MoviePilot Agent 工具。"""
+
+    name: str = "mcp_external_tool"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Admin,
+    ]
+    description: str = "Call an external MCP tool configured for MoviePilot Agent."
+    args_schema: dict[str, Any] = {"type": "object", "properties": {}, "required": []}
+    require_admin: bool = True
+
+    _spec: AgentMcpToolSpec = PrivateAttr()
+
+    def __init__(self, spec: AgentMcpToolSpec, session_id: str, user_id: str) -> None:
+        super().__init__(
+            session_id=session_id,
+            user_id=user_id,
+            name=spec.agent_tool_name,
+            description=spec.description
+            or f"Call external MCP tool {spec.name} on {spec.server.name}.",
+            args_schema=spec.input_schema,
+            require_admin=spec.server.require_admin,
+        )
+        self._spec = spec
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """根据 MCP 工具信息生成友好的提示消息。"""
+        return f"调用 MCP 工具: {self._spec.server.name}/{self._spec.name}"
+
+    async def run(self, **kwargs) -> str:
+        """
+        调用外部 MCP 工具。
+
+        :param kwargs: 传递给外部 MCP 工具的参数
+        :return: MCP 工具返回内容
+        """
+        result = await agent_mcp_manager.call_server_tool(
+            server=self._spec.server,
+            tool_name=self._spec.name,
+            arguments=kwargs,
+        )
+        return self._format_mcp_result(result)
+
+    @staticmethod
+    def _format_mcp_result(result: Any) -> str:
+        """将 MCP tools/call 返回结构转换为 Agent 可读文本。"""
+        if isinstance(result, dict):
+            content = result.get("content")
+            if isinstance(content, list):
+                parts = []
+                for item in content:
+                    if not isinstance(item, dict):
+                        continue
+                    if item.get("type") == "text" and item.get("text") is not None:
+                        parts.append(str(item["text"]))
+                    elif item:
+                        parts.append(json.dumps(item, ensure_ascii=False, default=str))
+                if parts:
+                    return "\n".join(parts)
+            if result.get("isError"):
+                return json.dumps(result, ensure_ascii=False, indent=2, default=str)
+        if isinstance(result, str):
+            return result
+        return json.dumps(result, ensure_ascii=False, indent=2, default=str)
+
+
+async def create_external_mcp_tools(
+    *,
+    session_id: str,
+    user_id: str,
+    channel: Optional[str] = None,
+    source: Optional[str] = None,
+    username: Optional[str] = None,
+    stream_handler=None,
+    agent_context: Optional[dict] = None,
+) -> list[McpExternalTool]:
+    """创建当前已启用的外部 MCP Agent 工具列表。"""
+    tools = []
+    for spec in await agent_mcp_manager.list_enabled_tool_specs():
+        tool = McpExternalTool(spec=spec, session_id=session_id, user_id=user_id)
+        tool.set_message_attr(channel=channel, source=source, username=username)
+        tool.set_stream_handler(stream_handler=stream_handler)
+        tool.set_agent_context(agent_context=agent_context)
+        tools.append(tool)
+    return tools

app/agent/tools/impl/modify_download.py

@@ -1,137 +0,0 @@
-"""修改下载任务工具"""
-
-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: Optional[str] = Field(None,
-        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
-    require_admin: bool = True
-
-    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)
-
-    @staticmethod
-    def _modify_download_sync(
-        hash_value: str,
-        action: Optional[str] = None,
-        tags: Optional[List[str]] = None,
-        downloader: Optional[str] = None,
-    ) -> List[str]:
-        """同步修改下载任务状态和标签，避免下载器 SDK 阻塞事件循环。"""
-        download_chain = DownloadChain()
-        results = []
-
-        if tags:
-            tag_result = download_chain.set_torrents_tag(
-                hashs=[hash_value], tags=tags, downloader=downloader
-            )
-            if tag_result:
-                results.append(f"成功设置标签：{', '.join(tags)}")
-            else:
-                results.append("设置标签失败，请检查任务是否存在或下载器是否可用")
-
-        if action:
-            action_result = download_chain.set_downloading(
-                hash_str=hash_value, 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 results
-
-    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}'。"
-
-            results = await self.run_blocking(
-                "downloader",
-                self._modify_download_sync,
-                hash,
-                action,
-                tags,
-                downloader,
-            )
-
-            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_agent_tasks.py

@@ -0,0 +1,88 @@
+import json
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
+from app.core.config import settings
+from app.db.agenttask_oper import AgentTaskOper
+
+
+class QueryAgentTasksInput(BaseModel):
+    """查询 Agent 自主定时任务的输入参数。"""
+
+    task_id: Optional[int] = Field(
+        None,
+        ge=1,
+        description="Optional task ID. Omit it to list tasks owned by the current user.",
+    )
+    enabled: Optional[bool] = Field(
+        None,
+        description="Optional enabled-state filter used when listing tasks.",
+    )
+
+
+class QueryAgentTasksTool(MoviePilotTool):
+    """查询当前用户创建的 Agent 自主定时任务。"""
+
+    name: str = "query_agent_tasks"
+    tags: list[str] = [ToolTag.Read, ToolTag.AgentTask, ToolTag.Admin]
+    description: str = (
+        "Query persistent autonomous agent tasks owned by the current user, including "
+        "reminders, monitoring tasks, and recurring agent work. Returns the integer "
+        "task_id, instructions, trigger, enabled state, next run time, and latest result. "
+        "Do not use this for MoviePilot system, plugin, or workflow scheduler services."
+    )
+    args_schema: Type[BaseModel] = QueryAgentTasksInput
+    require_admin: bool = True
+
+    def get_tool_message(self, **kwargs: object) -> Optional[str]:
+        """生成查询定时任务的提示消息。"""
+        task_id = kwargs.get("task_id")
+        return f"查询自主定时任务：{task_id}" if task_id else "查询自主定时任务"
+
+    def _query_tasks(
+            self,
+            task_id: Optional[int],
+            enabled: Optional[bool],
+    ) -> list[dict]:
+        """读取当前用户的任务及运行时下一次触发时间。"""
+        from app.scheduler import Scheduler
+
+        oper = AgentTaskOper()
+        if task_id:
+            task = oper.get(task_id=task_id, user_id=str(self._user_id))
+            tasks = [task] if task else []
+        else:
+            tasks = oper.list(user_id=str(self._user_id), enabled=enabled)
+        scheduler = Scheduler()
+        result = []
+        for task in tasks:
+            data = oper.to_dict(
+                task,
+                next_run_at=scheduler.get_agent_task_next_run(task.id),
+                timezone=settings.TZ,
+            )
+            result.append(data)
+        return result
+
+    async def run(
+            self,
+            task_id: Optional[int] = None,
+            enabled: Optional[bool] = None,
+            **kwargs: object,
+    ) -> str:
+        """查询 Agent 自主定时任务。"""
+        payload = QueryAgentTasksInput(task_id=task_id, enabled=enabled)
+        tasks = await self.run_blocking(
+            "db",
+            self._query_tasks,
+            payload.task_id,
+            payload.enabled,
+        )
+        return json.dumps(
+            {"total": len(tasks), "tasks": tasks},
+            ensure_ascii=False,
+            indent=2,
+        )

app/agent/tools/impl/query_builtin_filter_rules.py

@@ -6,6 +6,7 @@ from typing import Optional, Type, List
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._filter_rule_utils import (
     get_builtin_rules,
     serialize_builtin_rule,
@@ -17,8 +18,6 @@ from app.log import logger
 class QueryBuiltinFilterRulesInput(BaseModel):
     """查询内置过滤规则工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     rule_ids: Optional[List[str]] = Field(
         None,
         description="Optional list of built-in rule IDs to query. If omitted, return all built-in rules.",
@@ -27,6 +26,10 @@ class QueryBuiltinFilterRulesInput(BaseModel):
 
 class QueryBuiltinFilterRulesTool(MoviePilotTool):
     name: str = "query_builtin_filter_rules"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.FilterRule,
+    ]
     description: str = (
         "Query built-in filter rules defined by the backend filter module. "
         "These rule IDs can be used directly inside rule_string expressions for filter rule groups. "

app/agent/tools/impl/query_custom_filter_rules.py

@@ -6,6 +6,7 @@ from typing import Optional, Type, List
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._filter_rule_utils import (
     collect_custom_rule_group_refs,
     get_custom_rules,
@@ -18,8 +19,6 @@ from app.log import logger
 class QueryCustomFilterRulesInput(BaseModel):
     """查询自定义过滤规则工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     rule_ids: Optional[List[str]] = Field(
         None,
         description="Optional list of custom rule IDs to query. If omitted, return all custom rules.",
@@ -32,6 +31,10 @@ class QueryCustomFilterRulesInput(BaseModel):
 
 class QueryCustomFilterRulesTool(MoviePilotTool):
     name: str = "query_custom_filter_rules"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.FilterRule,
+    ]
     description: str = (
         "Query custom filter rules stored in CustomFilterRules. "
         "Custom rules can be referenced from rule_string expressions in filter rule groups. "

app/agent/tools/impl/query_custom_identifiers.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.db.systemconfig_oper import SystemConfigOper
 from app.log import logger
 from app.schemas.types import SystemConfigKey
@@ -14,12 +15,15 @@ from app.schemas.types import SystemConfigKey
 class QueryCustomIdentifiersInput(BaseModel):
     """查询自定义识别词工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
 
 
 class QueryCustomIdentifiersTool(MoviePilotTool):
     name: str = "query_custom_identifiers"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.FilterRule,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Query all currently configured custom identifiers (自定义识别词). "
         "Returns the list of identifier rules used for preprocessing torrent/file names before media recognition. "

app/agent/tools/impl/query_directory_settings.py

@@ -6,13 +6,13 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.helper.directory import DirectoryHelper
 from app.log import logger
 
 
 class QueryDirectorySettingsInput(BaseModel):
     """查询系统目录设置工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     directory_type: Optional[str] = Field("all",
                                           description="Filter directories by type: 'download' for download directories, 'library' for media library directories, 'all' for all directories")
     storage_type: Optional[str] = Field("all",
@@ -23,6 +23,12 @@ class QueryDirectorySettingsInput(BaseModel):
 
 class QueryDirectorySettingsTool(MoviePilotTool):
     name: str = "query_directory_settings"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Directory,
+        ToolTag.Settings,
+        ToolTag.Admin,
+    ]
     description: str = "Query system directory configuration settings (NOT file listings). Returns configured directory paths, storage types, transfer modes, and other directory-related settings. Use 'list_directory' to list actual files and folders in a directory."
     require_admin: bool = True
     args_schema: Type[BaseModel] = QueryDirectorySettingsInput

app/agent/tools/impl/query_doctor_report.py

@@ -0,0 +1,125 @@
+"""查询 MoviePilot Doctor 诊断报告工具。"""
+
+import json
+from typing import Any, Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
+from app.doctor import run_doctor
+from app.log import logger
+
+
+class QueryDoctorReportInput(BaseModel):
+    """查询 Doctor 诊断报告工具的输入参数模型。"""
+
+    deep: Optional[bool] = Field(
+        False,
+        description=(
+            "Whether to run deeper checks. When true, doctor may perform slower environment probes "
+            "such as PostgreSQL TCP connectivity checks."
+        ),
+    )
+    include_details: Optional[bool] = Field(
+        True,
+        description=(
+            "Whether to include full doctor findings with details and context. Set false for a compact "
+            "summary when only overall status and finding titles are needed."
+        ),
+    )
+
+
+class QueryDoctorReportTool(MoviePilotTool):
+    """
+    Doctor 离线诊断报告查询工具。
+    """
+
+    name: str = "query_doctor_report"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.System,
+        ToolTag.Admin,
+    ]
+    description: str = (
+        "Run MoviePilot Doctor in read-only mode and return a structured diagnostic report for troubleshooting. "
+        "Use this tool when analyzing startup failures, Docker/runtime issues, port conflicts, dependency problems, "
+        "database health, frontend assets, safe mode, or recent log error clues. Plugin-only log findings remain "
+        "visible with affects_report_status=false and do not downgrade the overall status. This tool never applies "
+        "fixes."
+    )
+    require_admin: bool = True
+    args_schema: Type[BaseModel] = QueryDoctorReportInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """根据查询参数生成友好的提示消息。"""
+        if kwargs.get("deep"):
+            return "运行 Doctor 深度诊断"
+        return "运行 Doctor 诊断"
+
+    @staticmethod
+    def _compact_report(report: dict[str, Any]) -> dict[str, Any]:
+        """压缩诊断报告，保留 Agent 判断问题所需的核心字段。"""
+        return {
+            "schema_version": report.get("schema_version"),
+            "status": report.get("status"),
+            "generated_at": report.get("generated_at"),
+            "version": report.get("version"),
+            "environment": report.get("environment"),
+            "summary": report.get("summary"),
+            "findings": [
+                {
+                    "id": item.get("id"),
+                    "severity": item.get("severity"),
+                    "status": item.get("status"),
+                    "title": item.get("title"),
+                    "fixable": item.get("fixable"),
+                    "fixed": item.get("fixed"),
+                    "affects_report_status": item.get("affects_report_status", True),
+                }
+                for item in report.get("findings") or []
+                if isinstance(item, dict)
+            ],
+        }
+
+    @staticmethod
+    def _run_doctor_report(deep: bool = False) -> dict[str, Any]:
+        """在线程池中运行只读 Doctor 诊断。"""
+        return run_doctor(deep=bool(deep)).to_dict()
+
+    async def run(
+        self,
+        deep: Optional[bool] = False,
+        include_details: Optional[bool] = True,
+        **kwargs,
+    ) -> str:
+        """
+        运行只读 Doctor 诊断并返回 JSON 字符串。
+        """
+        logger.info(
+            f"执行工具: {self.name}, deep={bool(deep)}, include_details={bool(include_details)}"
+        )
+        try:
+            report = await self.run_blocking("default", self._run_doctor_report, bool(deep))
+            if not include_details:
+                report = self._compact_report(report)
+            return json.dumps(
+                {
+                    "success": True,
+                    "deep": bool(deep),
+                    "include_details": bool(include_details),
+                    "report": report,
+                },
+                ensure_ascii=False,
+                indent=2,
+                default=str,
+            )
+        except Exception as err:
+            logger.error(f"查询 Doctor 诊断报告失败: {err}", exc_info=True)
+            return json.dumps(
+                {
+                    "success": False,
+                    "message": f"查询 Doctor 诊断报告时发生错误: {str(err)}",
+                },
+                ensure_ascii=False,
+            )

app/agent/tools/impl/query_download_tasks.py

@@ -1,25 +1,33 @@
 """查询下载工具"""
 
 import json
-from typing import Any, Dict, List, Optional, Type, Union
+from typing import Any, Dict, List, Optional, Type
 
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 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, media_type_to_agent
+from app.schemas import DownloaderTorrent
+from app.schemas.types import TorrentQueryStatus, media_type_to_agent
 
 
 class QueryDownloadTasksInput(BaseModel):
     """查询下载工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     downloader: Optional[str] = Field(None,
                                       description="Name of specific downloader to query (optional, if not provided queries all configured downloaders)")
     status: Optional[str] = Field("all",
                                   description="Filter downloads by status: 'downloading' for active downloads, 'completed' for finished downloads, 'paused' for paused downloads, 'all' for all downloads")
+    include_all_tags: Optional[bool] = Field(
+        False,
+        description="Include tasks without the MoviePilot built-in tag. Default false keeps the normal MoviePilot task scope.",
+    )
+    include_trackers: Optional[bool] = Field(
+        False,
+        description="Include tracker URLs when supported. Hash queries always include trackers.",
+    )
     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')")
@@ -27,30 +35,53 @@ class QueryDownloadTasksInput(BaseModel):
 
 class QueryDownloadTasksTool(MoviePilotTool):
     name: str = "query_download_tasks"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Download,
+    ]
     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
-    def _get_all_torrents(download_chain: DownloadChain, downloader: Optional[str] = None) -> List[Union[TransferTorrent, DownloadingTorrent]]:
+    def _normalize_query_status(status: Optional[str]) -> TorrentQueryStatus:
+        """
+        归一下载任务查询状态。
+        """
+        status_value = str(status or "").strip().lower()
+        if not status_value or status_value == TorrentQueryStatus.ALL.value:
+            return TorrentQueryStatus.ALL
+        if status_value in {"completed", "complete", "seeding"}:
+            return TorrentQueryStatus.COMPLETED
+        if status_value in {"paused", "pause"}:
+            return TorrentQueryStatus.PAUSED
+        if status_value == TorrentQueryStatus.DOWNLOADING.value:
+            return TorrentQueryStatus.DOWNLOADING
+        return TorrentQueryStatus.ALL
+
+    @staticmethod
+    def _normalize_include_all_tags(include_all_tags: Any) -> bool:
+        """
+        归一全部标签查询开关。
+        """
+        if isinstance(include_all_tags, bool):
+            return include_all_tags
+        if isinstance(include_all_tags, str):
+            return include_all_tags.strip().lower() in {"1", "true", "yes", "on", "是"}
+        return bool(include_all_tags)
+
+    @staticmethod
+    def _get_all_torrents(
+        download_chain: DownloadChain,
+        downloader: Optional[str] = None,
+        include_all_tags: bool = False,
+    ) -> List[DownloaderTorrent]:
         """
         查询所有状态的任务（包括下载中和已完成的任务）
         """
-        all_torrents = []
-        # 查询下载的任务
-        downloading_torrents = download_chain.list_torrents(
-            downloader=downloader, 
-            status=TorrentStatus.DOWNLOADING
-        ) or []
-        all_torrents.extend(downloading_torrents)
-        
-        # 查询已完成的任务（可转移状态）
-        transfer_torrents = download_chain.list_torrents(
+        return download_chain.list_torrents(
             downloader=downloader,
-            status=TorrentStatus.TRANSFER
+            include_all_tags=include_all_tags,
         ) or []
-        all_torrents.extend(transfer_torrents)
-        
-        return all_torrents
 
     @staticmethod
     def _format_progress(progress: Optional[float]) -> Optional[str]:
@@ -66,7 +97,7 @@ class QueryDownloadTasksTool(MoviePilotTool):
 
     @staticmethod
     def _apply_download_history(
-        torrent: Union[TransferTorrent, DownloadingTorrent], history: Any
+        torrent: DownloaderTorrent, history: Any
     ) -> None:
         """将下载历史中的补充信息回填到下载任务结果中。"""
         if not history:
@@ -86,7 +117,7 @@ class QueryDownloadTasksTool(MoviePilotTool):
 
     @classmethod
     def _load_history_map(
-        cls, torrents: List[Union[TransferTorrent, DownloadingTorrent]]
+        cls, torrents: List[DownloaderTorrent]
     ) -> Dict[str, Any]:
         """批量加载下载历史，避免逐条查询形成 N+1。"""
         hashes = [torrent.hash for torrent in torrents if getattr(torrent, "hash", None)]
@@ -102,15 +133,23 @@ class QueryDownloadTasksTool(MoviePilotTool):
         hash_value: Optional[str] = None,
         title: Optional[str] = None,
         tag: Optional[str] = None,
+        include_all_tags: bool = False,
+        include_trackers: bool = False,
     ) -> Dict[str, Any]:
         """
         同步查询下载器和下载历史，整个链路放在线程池中执行。
         """
         download_chain = DownloadChain()
+        query_status = cls._normalize_query_status(status)
+        include_all_tags = cls._normalize_include_all_tags(include_all_tags)
 
         if hash_value:
             torrents = (
-                download_chain.list_torrents(downloader=downloader, hashs=[hash_value])
+                download_chain.list_torrents(
+                    downloader=downloader,
+                    hashs=[hash_value],
+                    include_all_tags=include_all_tags,
+                )
                 or []
             )
             if not torrents:
@@ -123,7 +162,11 @@ class QueryDownloadTasksTool(MoviePilotTool):
                 cls._apply_download_history(torrent, history_map.get(torrent.hash))
             filtered_downloads = list(torrents)
         elif title:
-            all_torrents = cls._get_all_torrents(download_chain, downloader)
+            all_torrents = cls._get_all_torrents(
+                download_chain,
+                downloader,
+                include_all_tags=include_all_tags,
+            )
             history_map = cls._load_history_map(all_torrents)
             filtered_downloads = []
             title_lower = title.lower()
@@ -145,7 +188,7 @@ class QueryDownloadTasksTool(MoviePilotTool):
             if not filtered_downloads:
                 return {"message": f"未找到标题包含 '{title}' 的下载任务"}
         else:
-            if status == "downloading":
+            if query_status == TorrentQueryStatus.DOWNLOADING and not include_all_tags:
                 downloads = download_chain.downloading(name=downloader) or []
                 filtered_downloads = [
                     dl
@@ -153,19 +196,12 @@ class QueryDownloadTasksTool(MoviePilotTool):
                     if not downloader or dl.downloader == downloader
                 ]
             else:
-                all_torrents = cls._get_all_torrents(download_chain, downloader)
-                filtered_downloads = []
-                for torrent in all_torrents:
-                    if downloader and torrent.downloader != downloader:
-                        continue
-                    if status == "completed" and torrent.state not in [
-                        "seeding",
-                        "completed",
-                    ]:
-                        continue
-                    if status == "paused" and torrent.state != "paused":
-                        continue
-                    filtered_downloads.append(torrent)
+                list_status = None if query_status == TorrentQueryStatus.ALL else query_status.value
+                filtered_downloads = download_chain.list_torrents(
+                    downloader=downloader,
+                    status=list_status,
+                    include_all_tags=include_all_tags,
+                ) or []
 
                 history_map = cls._load_history_map(filtered_downloads)
                 for torrent in filtered_downloads:
@@ -182,6 +218,16 @@ class QueryDownloadTasksTool(MoviePilotTool):
         if not filtered_downloads:
             return {"message": "未找到相关下载任务"}
 
+        if hash_value or include_trackers:
+            for torrent in filtered_downloads:
+                if not getattr(torrent, "hash", None):
+                    continue
+                tracker_map = download_chain.get_torrent_trackers(
+                    hash_string=torrent.hash,
+                    downloader=getattr(torrent, "downloader", None) or downloader,
+                ) or {}
+                torrent.trackers = tracker_map.get(getattr(torrent, "downloader", None)) or []
+
         return {"downloads": filtered_downloads}
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
@@ -190,6 +236,9 @@ class QueryDownloadTasksTool(MoviePilotTool):
         status = kwargs.get("status", "all")
         hash_value = kwargs.get("hash")
         title = kwargs.get("title")
+        include_all_tags = self._normalize_include_all_tags(
+            kwargs.get("include_all_tags", False)
+        )
         
         parts = ["查询下载任务"]
         
@@ -208,6 +257,10 @@ class QueryDownloadTasksTool(MoviePilotTool):
         tag = kwargs.get("tag")
         if tag:
             parts.append(f"标签: {tag}")
+        if include_all_tags:
+            parts.append("范围: 全部标签")
+        if kwargs.get("include_trackers"):
+            parts.append("包含Tracker")
         
         return " | ".join(parts) if len(parts) > 1 else parts[0]
 
@@ -215,8 +268,15 @@ class QueryDownloadTasksTool(MoviePilotTool):
                   status: Optional[str] = "all",
                   hash: Optional[str] = None,
                   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}")
+                  tag: Optional[str] = None,
+                  include_all_tags: Optional[bool] = False,
+                  include_trackers: Optional[bool] = False,
+                  **kwargs) -> str:
+        logger.info(
+            f"执行工具: {self.name}, 参数: downloader={downloader}, status={status}, "
+            f"hash={hash}, title={title}, tag={tag}, include_all_tags={include_all_tags}, "
+            f"include_trackers={include_trackers}"
+        )
         try:
             payload = await self.run_blocking(
                 "downloader",
@@ -226,6 +286,8 @@ class QueryDownloadTasksTool(MoviePilotTool):
                 hash,
                 title,
                 tag,
+                self._normalize_include_all_tags(include_all_tags),
+                self._normalize_include_all_tags(include_trackers),
             )
             if payload.get("message"):
                 return payload["message"]
@@ -251,6 +313,16 @@ class QueryDownloadTasksTool(MoviePilotTool):
                         "upspeed": getattr(d, "upspeed", None),
                         "dlspeed": getattr(d, "dlspeed", None),
                         "tags": d.tags,
+                        "save_path": getattr(d, "save_path", None),
+                        "content_path": getattr(d, "content_path", None) or (
+                            d.path.as_posix() if getattr(d, "path", None) else None
+                        ),
+                        "category": getattr(d, "category", None),
+                        "download_limit": getattr(d, "download_limit", None),
+                        "upload_limit": getattr(d, "upload_limit", None),
+                        "ratio_limit": getattr(d, "ratio_limit", None),
+                        "seeding_time_limit": getattr(d, "seeding_time_limit", None),
+                        "trackers": getattr(d, "trackers", None) or [],
                         "left_time": getattr(d, "left_time", None)
                     }
                     # 精简 media 字段

app/agent/tools/impl/query_downloaders.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.db.systemconfig_oper import SystemConfigOper
 from app.log import logger
 from app.schemas.types import SystemConfigKey
@@ -13,13 +14,17 @@ from app.schemas.types import SystemConfigKey
 
 class QueryDownloadersInput(BaseModel):
     """查询下载器工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
-
-
 class QueryDownloadersTool(MoviePilotTool):
     name: str = "query_downloaders"
-    description: str = "Query downloader configuration and list all available downloaders. Shows downloader status, connection details, and configuration settings."
-    require_admin: bool = True
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Download,
+    ]
+    description: str = (
+        "Query downloader configuration and list available downloaders. Non-admin users receive "
+        "a safe view with only the fields needed to choose a downloader, without host, account, "
+        "password, token or API key values."
+    )
     args_schema: Type[BaseModel] = QueryDownloadersInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
@@ -31,11 +36,35 @@ class QueryDownloadersTool(MoviePilotTool):
         """从内存配置缓存中读取下载器配置。"""
         return SystemConfigOper().get(SystemConfigKey.Downloaders)
 
+    @staticmethod
+    def _sanitize_downloaders_config(downloaders_config: list) -> list:
+        """
+        生成普通用户可见的下载器配置视图。
+
+        :param downloaders_config: 系统下载器完整配置列表
+        :return: 仅包含名称、类型和启用状态的安全配置列表
+        """
+        safe_fields = ("name", "type", "enabled", "default", "priority")
+        safe_downloaders = []
+        for downloader in downloaders_config:
+            if not isinstance(downloader, dict):
+                continue
+            safe_downloaders.append({
+                key: downloader.get(key)
+                for key in safe_fields
+                if key in downloader
+            })
+        return safe_downloaders
+
     async def run(self, **kwargs) -> str:
         logger.info(f"执行工具: {self.name}")
         try:
             downloaders_config = self._load_downloaders_config()
             if downloaders_config:
+                if not await self.is_admin_user():
+                    downloaders_config = self._sanitize_downloaders_config(
+                        downloaders_config
+                    )
                 return json.dumps(downloaders_config, ensure_ascii=False, indent=2)
             return "未配置下载器。"
         except Exception as e:

app/agent/tools/impl/query_episode_schedule.py

@@ -6,13 +6,13 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.tmdb import TmdbChain
 from app.log import logger
 
 
 class QueryEpisodeScheduleInput(BaseModel):
     """查询剧集上映时间工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, 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 (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)")
@@ -20,6 +20,10 @@ class QueryEpisodeScheduleInput(BaseModel):
 
 class QueryEpisodeScheduleTool(MoviePilotTool):
     name: str = "query_episode_schedule"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Media,
+    ]
     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
 

app/agent/tools/impl/query_installed_plugins.py

@@ -6,9 +6,11 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._plugin_tool_utils import (
     DEFAULT_PLUGIN_CANDIDATE_LIMIT,
     MAX_PLUGIN_CANDIDATE_LIMIT,
+    enrich_installed_plugin_sources,
     list_installed_plugins,
     search_plugin_candidates,
     summarize_candidates,
@@ -20,8 +22,6 @@ from app.log import logger
 class QueryInstalledPluginsInput(BaseModel):
     """查询已安装插件工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     query: Optional[str] = Field(
         None,
         description="Optional keyword to filter installed plugins by plugin ID, name, description, or author.",
@@ -30,10 +30,21 @@ class QueryInstalledPluginsInput(BaseModel):
         DEFAULT_PLUGIN_CANDIDATE_LIMIT,
         description="Maximum number of plugins to return. Defaults to 50, capped at 200.",
     )
+    force_refresh_market: bool = Field(
+        False,
+        description="Whether to refresh plugin market caches before completing missing repo_url values.",
+    )
 
 
 class QueryInstalledPluginsTool(MoviePilotTool):
+    """查询已安装插件并返回 Agent 可消费的摘要信息。"""
+
     name: str = "query_installed_plugins"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Plugin,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Query installed plugins in MoviePilot. Returns all installed plugins or filters them by keywords. "
         "Use this tool to find the exact plugin_id before uninstall_plugin or other plugin management tools are used."
@@ -61,9 +72,15 @@ class QueryInstalledPluginsTool(MoviePilotTool):
         self,
         query: Optional[str] = None,
         max_results: Optional[int] = DEFAULT_PLUGIN_CANDIDATE_LIMIT,
+        force_refresh_market: bool = False,
         **kwargs,
     ) -> str:
-        logger.info(f"执行工具: {self.name}, 参数: query={query}")
+        """
+        查询已安装插件列表，并在可能时补齐插件来源仓库地址。
+        """
+        logger.info(
+            f"执行工具: {self.name}, 参数: query={query}, force_refresh_market={force_refresh_market}"
+        )
         try:
             installed_plugins = list_installed_plugins()
             if not installed_plugins:
@@ -71,6 +88,10 @@ class QueryInstalledPluginsTool(MoviePilotTool):
                     {"success": False, "message": "当前没有已安装的插件"},
                     ensure_ascii=False,
                 )
+            installed_plugins = await enrich_installed_plugin_sources(
+                installed_plugins,
+                force_refresh=force_refresh_market,
+            )
 
             limit = self._clamp_results(max_results)
             if query:

app/agent/tools/impl/query_library_exists.py

@@ -8,6 +8,7 @@ from typing import Optional, Type, Any
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.mediaserver import MediaServerChain
 from app.helper.mediaserver import MediaServerHelper
 from app.log import logger
@@ -76,29 +77,40 @@ def _build_tv_server_result(existing_seasons: OrderedDict, total_seasons: Ordere
 
 class QueryLibraryExistsInput(BaseModel):
     """查询媒体库工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
-    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.")
+    tmdb_id: Optional[int] = Field(None, description="TMDB media ID")
+    douban_id: Optional[str] = Field(None, description="Douban media ID")
+    bangumi_id: Optional[int] = Field(None, description="Bangumi media ID")
+    anilist_id: Optional[int] = Field(None, description="AniList media ID")
+    media_source: Optional[str] = Field(None, description="Media metadata source")
+    media_id: Optional[str] = Field(None, description="Native ID for media_source")
     media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")
 
 
 class QueryLibraryExistsTool(MoviePilotTool):
     name: str = "query_library_exists"
-    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."
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Library,
+        ToolTag.Media,
+    ]
+    description: str = "Check whether media already exists in Plex, Emby, or Jellyfin by a TMDB, Douban, Bangumi, AniList, or source-native media ID. Results are grouped by media server; TV results include existing episodes, total episodes, and missing episodes/seasons."
     args_schema: Type[BaseModel] = QueryLibraryExistsInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据查询参数生成友好的提示消息"""
-        tmdb_id = kwargs.get("tmdb_id")
-        douban_id = kwargs.get("douban_id")
         media_type = kwargs.get("media_type")
-
-        if tmdb_id:
-            message = f"查询媒体库: TMDB={tmdb_id}"
-        elif douban_id:
-            message = f"查询媒体库: 豆瓣={douban_id}"
-        else:
-            message = "查询媒体库"
+        identities = (
+            ("TMDB", kwargs.get("tmdb_id")),
+            ("豆瓣", kwargs.get("douban_id")),
+            ("Bangumi", kwargs.get("bangumi_id")),
+            ("AniList", kwargs.get("anilist_id")),
+            (kwargs.get("media_source") or "媒体源", kwargs.get("media_id")),
+        )
+        label, identity = next(
+            ((label, identity) for label, identity in identities if identity is not None),
+            (None, None),
+        )
+        message = f"查询媒体库: {label}={identity}" if label else "查询媒体库"
         if media_type:
             message += f" [{media_type}]"
         return message
@@ -114,11 +126,13 @@ class QueryLibraryExistsTool(MoviePilotTool):
         return MediaServerChain().media_exists(mediainfo=mediainfo, server=server)
 
     async def run(self, tmdb_id: Optional[int] = None, douban_id: Optional[str] = None,
+                  bangumi_id: Optional[int] = None, anilist_id: Optional[int] = None,
+                  media_source: Optional[str] = None, media_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 tmdb_id and not douban_id:
-                return "参数错误：tmdb_id 和 douban_id 至少需要提供一个，请先使用 search_media 工具获取媒体 ID。"
+            if not any((tmdb_id, douban_id, bangumi_id, anilist_id, media_id)):
+                return "参数错误：至少需要提供一个媒体 ID，请先使用 search_media 工具获取媒体信息。"
 
             media_type_enum = None
             if media_type:
@@ -130,11 +144,15 @@ class QueryLibraryExistsTool(MoviePilotTool):
             mediainfo = await media_chain.async_recognize_media(
                 tmdbid=tmdb_id,
                 doubanid=douban_id,
+                bangumiid=bangumi_id,
+                anilistid=anilist_id,
+                source=media_source,
+                mediaid=media_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}"
+                identity = media_id or tmdb_id or douban_id or bangumi_id or anilist_id
+                return f"未识别到媒体信息: {identity}"
 
             # 2. 遍历所有媒体服务器，分别查询存在性信息
             server_results = OrderedDict()

app/agent/tools/impl/query_library_latest.py

@@ -7,6 +7,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.mediaserver import MediaServerChain
 from app.helper.service import ServiceConfigHelper
 from app.log import logger
@@ -17,8 +18,6 @@ PAGE_SIZE = 20
 class QueryLibraryLatestInput(BaseModel):
     """查询媒体服务器最近入库影片工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     server: Optional[str] = Field(
         None,
         description="Media server name (optional, if not specified queries all enabled media servers)",
@@ -30,6 +29,11 @@ class QueryLibraryLatestInput(BaseModel):
 
 class QueryLibraryLatestTool(MoviePilotTool):
     name: str = "query_library_latest"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Library,
+        ToolTag.Media,
+    ]
     description: str = "Query the latest media items added to the media server (Plex, Emby, Jellyfin). Returns recently added movies and TV series with their titles, images, links, and other metadata. Supports pagination with 20 items per page."
     args_schema: Type[BaseModel] = QueryLibraryLatestInput
 

app/agent/tools/impl/query_market_plugins.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._plugin_tool_utils import (
     DEFAULT_PLUGIN_CANDIDATE_LIMIT,
     MAX_PLUGIN_CANDIDATE_LIMIT,
@@ -20,8 +21,6 @@ from app.log import logger
 class QueryMarketPluginsInput(BaseModel):
     """查询插件市场工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     query: Optional[str] = Field(
         None,
         description="Optional keyword to filter plugin market results by plugin ID, name, description, or author.",
@@ -38,6 +37,11 @@ class QueryMarketPluginsInput(BaseModel):
 
 class QueryMarketPluginsTool(MoviePilotTool):
     name: str = "query_market_plugins"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Plugin,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Query available plugins from the plugin market and local plugin repositories. "
         "Can return the full plugin list or filter by keywords before install_plugin is used."

app/agent/tools/impl/query_media_detail.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.chain.media import MediaChain
 from app.log import logger
 from app.schemas.types import MediaType
@@ -17,32 +18,52 @@ SEASON_PREVIEW_LIMIT = 100
 
 class QueryMediaDetailInput(BaseModel):
     """查询媒体详情工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     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)")
+    bangumi_id: Optional[int] = Field(None, description="Bangumi media ID")
+    anilist_id: Optional[int] = Field(None, description="AniList media ID")
+    media_source: Optional[str] = Field(None, description="Media metadata source")
+    media_id: Optional[str] = Field(None, description="Native ID for media_source")
     media_type: str = Field(..., description="Allowed values: movie, tv")
 
 
 class QueryMediaDetailTool(MoviePilotTool):
     name: str = "query_media_detail"
-    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."
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Media,
+    ]
+    description: str = "Query supplementary media details from a metadata source by ID and media_type. Accepts a TMDB, Douban, Bangumi, AniList, or source-native media ID. 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")
-        douban_id = kwargs.get("douban_id")
-        if tmdb_id:
-            return f"查询媒体详情: TMDB ID {tmdb_id}"
-        return f"查询媒体详情: 豆瓣 ID {douban_id}"
+        identities = (
+            ("TMDB", kwargs.get("tmdb_id")),
+            ("豆瓣", kwargs.get("douban_id")),
+            ("Bangumi", kwargs.get("bangumi_id")),
+            ("AniList", kwargs.get("anilist_id")),
+        )
+        for label, identity in identities:
+            if identity is not None:
+                return f"查询媒体详情: {label} ID {identity}"
+        return (
+            f"查询媒体详情: {kwargs.get('media_source') or '媒体源'} "
+            f"ID {kwargs.get('media_id')}"
+        )
 
-    async def run(self, media_type: str, tmdb_id: Optional[int] = None, douban_id: Optional[str] = None, **kwargs) -> str:
+    async def run(
+            self, media_type: str, tmdb_id: Optional[int] = None,
+            douban_id: Optional[str] = None, bangumi_id: Optional[int] = None,
+            anilist_id: Optional[int] = None, media_source: Optional[str] = None,
+            media_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:
+        if not any((tmdb_id, douban_id, bangumi_id, anilist_id, media_id)):
             return json.dumps({
                 "success": False,
-                "message": "必须提供 tmdb_id 或 douban_id 之一"
+                "message": "必须提供至少一个媒体 ID"
             }, ensure_ascii=False)
 
         try:
@@ -55,10 +76,22 @@ class QueryMediaDetailTool(MoviePilotTool):
                     "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)
+            mediainfo = await media_chain.async_recognize_media(
+                tmdbid=tmdb_id,
+                doubanid=douban_id,
+                bangumiid=bangumi_id,
+                anilistid=anilist_id,
+                source=media_source,
+                mediaid=media_id,
+                mtype=media_type_enum,
+            )
 
             if not mediainfo:
-                id_info = f"TMDB ID {tmdb_id}" if tmdb_id else f"豆瓣 ID {douban_id}"
+                id_info = (
+                    f"{media_source or '媒体源'} ID {media_id}"
+                    if media_id else
+                    f"媒体 ID {tmdb_id or douban_id or bangumi_id or anilist_id}"
+                )
                 return json.dumps({
                     "success": False,
                     "message": f"未找到 {id_info} 的媒体信息"
@@ -135,5 +168,9 @@ class QueryMediaDetailTool(MoviePilotTool):
                 "success": False,
                 "message": error_message,
                 "tmdb_id": tmdb_id,
-                "douban_id": douban_id
+                "douban_id": douban_id,
+                "bangumi_id": bangumi_id,
+                "anilist_id": anilist_id,
+                "media_source": media_source,
+                "media_id": media_id,
             }, ensure_ascii=False)

app/agent/tools/impl/query_personas.py

@@ -7,14 +7,13 @@ from pydantic import BaseModel, Field
 
 from app.agent.runtime import agent_runtime_manager
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.log import logger
 
 
 class QueryPersonasInput(BaseModel):
     """查询人格工具的输入参数模型。"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     query: Optional[str] = Field(
         None,
         description=(
@@ -26,6 +25,10 @@ class QueryPersonasInput(BaseModel):
 
 class QueryPersonasTool(MoviePilotTool):
     name: str = "query_personas"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Persona,
+    ]
     description: str = (
         "List all available personas (人格) and show which one is currently active. "
         "Use this before switching persona when the user asks for a different speaking style but does not name "

app/agent/tools/impl/query_plugin_capabilities.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.core.plugin import PluginManager
 from app.log import logger
 
@@ -13,8 +14,6 @@ from app.log import logger
 class QueryPluginCapabilitiesInput(BaseModel):
     """查询插件能力工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        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. "
@@ -25,6 +24,11 @@ class QueryPluginCapabilitiesInput(BaseModel):
 
 class QueryPluginCapabilitiesTool(MoviePilotTool):
     name: str = "query_plugin_capabilities"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Plugin,
+        ToolTag.Admin,
+    ]
     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_slash_command tool. "

app/agent/tools/impl/query_plugin_config.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._plugin_tool_utils import get_plugin_snapshot
 from app.core.plugin import PluginManager
 from app.log import logger
@@ -14,8 +15,6 @@ from app.log import logger
 class QueryPluginConfigInput(BaseModel):
     """查询插件配置工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="The plugin ID to query. Use query_installed_plugins first to discover valid plugin IDs.",
@@ -24,6 +23,11 @@ class QueryPluginConfigInput(BaseModel):
 
 class QueryPluginConfigTool(MoviePilotTool):
     name: str = "query_plugin_config"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Plugin,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Query the saved configuration of an installed plugin. "
         "Returns the current saved config and, when available, the plugin's default config model. "

app/agent/tools/impl/query_plugin_data.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._plugin_tool_utils import (
     PLUGIN_DATA_KEY_PREVIEW_LIMIT,
     build_preview_payload,
@@ -18,8 +19,6 @@ from app.log import logger
 class QueryPluginDataInput(BaseModel):
     """查询插件数据工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     plugin_id: str = Field(
         ...,
         description="The plugin ID to query. Use query_installed_plugins first to discover valid plugin IDs.",
@@ -36,6 +35,11 @@ class QueryPluginDataInput(BaseModel):
 
 class QueryPluginDataTool(MoviePilotTool):
     name: str = "query_plugin_data"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Plugin,
+        ToolTag.Admin,
+    ]
     description: str = (
         "Query persisted data of an installed plugin. "
         "Optionally specify a key to read a single data item; otherwise all plugin data entries are returned. "

app/agent/tools/impl/query_popular_subscribes.py

@@ -7,8 +7,9 @@ import cn2an
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.core.context import MediaInfo
-from app.helper.subscribe import SubscribeHelper
+from app.helper.server import MoviePilotServerHelper
 from app.log import logger
 from app.schemas.types import MediaType, media_type_to_agent
 
@@ -17,7 +18,6 @@ MAX_PAGE_SIZE = 50
 
 class QueryPopularSubscribesInput(BaseModel):
     """查询热门订阅工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     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, max: 50)")
@@ -30,6 +30,11 @@ class QueryPopularSubscribesInput(BaseModel):
 
 class QueryPopularSubscribesTool(MoviePilotTool):
     name: str = "query_popular_subscribes"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Subscription,
+        ToolTag.Recommendation,
+    ]
     description: str = "Query popular subscriptions based on user shared data. Shows media with the most subscribers, supports filtering by genre, rating, minimum subscribers, and pagination."
     args_schema: Type[BaseModel] = QueryPopularSubscribesInput
 
@@ -77,8 +82,7 @@ class QueryPopularSubscribesTool(MoviePilotTool):
             if not media_type_enum:
                 return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv'"
 
-            subscribe_helper = SubscribeHelper()
-            subscribes = await subscribe_helper.async_get_statistic(
+            subscribes = await MoviePilotServerHelper.async_get_subscribe_statistic(
                 stype=media_type_enum.to_agent(),
                 page=page,
                 count=count,
@@ -114,7 +118,7 @@ class QueryPopularSubscribesTool(MoviePilotTool):
                 # 处理标题
                 title = sub.get("name")
                 season = sub.get("season")
-                if season and int(season) > 1 and media.tmdb_id:
+                if season not in (None, "") and int(season) != 1 and media.tmdb_id:
                     # 小写数据转大写
                     season_str = cn2an.an2cn(season, "low")
                     title = f"{title} 第{season_str}季"
@@ -122,6 +126,8 @@ class QueryPopularSubscribesTool(MoviePilotTool):
                 media.year = sub.get("year")
                 media.douban_id = sub.get("doubanid")
                 media.bangumi_id = sub.get("bangumiid")
+                media.anilist_id = sub.get("anilistid")
+                media.source = sub.get("media_source")
                 media.tvdb_id = sub.get("tvdbid")
                 media.imdb_id = sub.get("imdbid")
                 media.season = sub.get("season")
@@ -145,6 +151,9 @@ class QueryPopularSubscribesTool(MoviePilotTool):
                     "tmdb_id": media_dict.get("tmdb_id"),
                     "douban_id": media_dict.get("douban_id"),
                     "bangumi_id": media_dict.get("bangumi_id"),
+                    "anilist_id": media_dict.get("anilist_id"),
+                    "media_source": media_dict.get("source"),
+                    "media_id": media_dict.get("media_id"),
                     "tvdb_id": media_dict.get("tvdb_id"),
                     "imdb_id": media_dict.get("imdb_id"),
                     "season": media_dict.get("season"),

app/agent/tools/impl/query_rule_groups.py

@@ -6,6 +6,7 @@ from typing import Optional, Type, List
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.agent.tools.impl._filter_rule_utils import (
     collect_rule_group_usages,
     get_rule_groups,
@@ -18,8 +19,6 @@ from app.log import logger
 class QueryRuleGroupsInput(BaseModel):
     """查询规则组工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     group_names: Optional[List[str]] = Field(
         None,
         description="Optional list of rule group names to query. If omitted, return all rule groups.",
@@ -32,6 +31,10 @@ class QueryRuleGroupsInput(BaseModel):
 
 class QueryRuleGroupsTool(MoviePilotTool):
     name: str = "query_rule_groups"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.FilterRule,
+    ]
     description: str = (
         "Query filter rule groups (过滤规则组 / 优先级规则组). "
         "Each rule group contains a rule_string made of built-in rules and/or custom rules. "

app/agent/tools/impl/query_schedulers.py

@@ -3,53 +3,77 @@
 import json
 from typing import Optional, Type
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.log import logger
 
 
 class QuerySchedulersInput(BaseModel):
-    """查询定时服务工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
+    """查询运行时定时服务的输入参数模型。"""
 
 
 class QuerySchedulersTool(MoviePilotTool):
+    """查询系统、插件和工作流注册的运行时定时服务。"""
+
     name: str = "query_schedulers"
-    description: str = "Query scheduled tasks and list all available scheduler jobs. Shows job status, next run time, and provider information."
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Scheduler,
+        ToolTag.Admin,
+    ]
+    description: str = (
+        "Query runtime scheduler services registered by MoviePilot system components, "
+        "plugins, and workflows. It excludes user-created autonomous agent tasks; use "
+        "query_agent_tasks for reminders, monitoring tasks, and other agent schedules."
+    )
     args_schema: Type[BaseModel] = QuerySchedulersInput
+    require_admin: bool = True
 
-    def get_tool_message(self, **kwargs) -> Optional[str]:
-        """生成友好的提示消息"""
-        return "查询定时服务"
+    def get_tool_message(self, **kwargs: object) -> Optional[str]:
+        """生成查询运行时定时服务的提示消息。"""
+        return "查询系统定时服务"
 
-    async def run(self, **kwargs) -> str:
+    async def run(self, **kwargs: object) -> str:
+        """查询非 Agent 自主任务的运行时定时服务。"""
         logger.info(f"执行工具: {self.name}")
         try:
-            from app.scheduler import Scheduler
+            from app.scheduler import AGENT_TASK_JOB_PREFIX, Scheduler
 
             scheduler = Scheduler()
-            schedulers = scheduler.list()
+            agent_task_prefix = f"{AGENT_TASK_JOB_PREFIX}-"
+            schedulers = [
+                scheduler_item
+                for scheduler_item in scheduler.list()
+                if not str(scheduler_item.id or "").startswith(agent_task_prefix)
+            ]
             if schedulers:
-                # 转换为字典列表以便JSON序列化
-                schedulers_list = []
-                for s in schedulers:
-                    schedulers_list.append({
-                        "id": s.id,
-                        "name": s.name,
-                        "provider": s.provider,
-                        "status": s.status,
-                        "next_run": s.next_run
-                    })
+                schedulers_list = [
+                    {
+                        "id": scheduler_item.id,
+                        "name": scheduler_item.name,
+                        "provider": scheduler_item.provider,
+                        "status": scheduler_item.status,
+                        "next_run": scheduler_item.next_run,
+                    }
+                    for scheduler_item in schedulers
+                ]
                 result_json = json.dumps(schedulers_list, ensure_ascii=False, indent=2)
-                # 限制最多30条结果
                 total_count = len(schedulers_list)
                 if total_count > 30:
                     limited_schedulers = schedulers_list[:30]
-                    limited_json = json.dumps(limited_schedulers, ensure_ascii=False, indent=2)
-                    return f"注意：查询结果共找到 {total_count} 条，为节省上下文空间，仅显示前 30 条结果。\n\n{limited_json}"
+                    limited_json = json.dumps(
+                        limited_schedulers,
+                        ensure_ascii=False,
+                        indent=2,
+                    )
+                    return (
+                        f"注意：查询结果共找到 {total_count} 条，为节省上下文空间，"
+                        f"仅显示前 30 条结果。\n\n{limited_json}"
+                    )
                 return result_json
-            return "未找到定时服务"
+            return "未找到系统、插件或工作流定时服务"
         except Exception as e:
             logger.error(f"查询定时服务失败: {e}", exc_info=True)
             return f"查询定时服务时发生错误: {str(e)}"

app/agent/tools/impl/query_site_userdata.py

@@ -6,9 +6,8 @@ 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.site import Site
-from app.db.models.siteuserdata import SiteUserData
+from app.agent.tools.tags import ToolTag
+from app.db.site_oper import SiteOper
 from app.log import logger
 
 SITE_USERDATA_DETAIL_PREVIEW_LIMIT = 10
@@ -23,8 +22,6 @@ def _preview_list(value, limit: int = SITE_USERDATA_DETAIL_PREVIEW_LIMIT) -> tup
 class QuerySiteUserdataInput(BaseModel):
     """查询站点用户数据工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        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 (can be obtained from query_sites tool)",
@@ -37,6 +34,11 @@ class QuerySiteUserdataInput(BaseModel):
 
 class QuerySiteUserdataTool(MoviePilotTool):
     name: str = "query_site_userdata"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Site,
+        ToolTag.Admin,
+    ]
     description: str = "Query user data for a specific site including username, user level, upload/download statistics, seeding information, bonus points, and other account details. Supports querying data for a specific date or latest data."
     require_admin: bool = True
     args_schema: Type[BaseModel] = QuerySiteUserdataInput
@@ -60,118 +62,115 @@ class QuerySiteUserdataTool(MoviePilotTool):
         )
 
         try:
-            # 获取数据库会话
-            async with AsyncSessionFactory() as db:
-                # 获取站点
-                site = await Site.async_get(db, site_id)
-                if not site:
-                    return json.dumps(
-                        {"success": False, "message": f"站点不存在: {site_id}"},
-                        ensure_ascii=False,
-                    )
-
-                # 获取站点用户数据
-                user_data_list = await SiteUserData.async_get_by_domain(
-                    db, domain=site.domain, workdate=workdate
+            site_oper = SiteOper()
+            site = await site_oper.async_get(site_id)
+            if not site:
+                return json.dumps(
+                    {"success": False, "message": f"站点不存在: {site_id}"},
+                    ensure_ascii=False,
                 )
 
-                if not user_data_list:
-                    return json.dumps(
-                        {
-                            "success": False,
-                            "message": f"站点 {site.name} ({site.domain}) 暂无用户数据",
-                            "site_id": site_id,
-                            "site_name": site.name,
-                            "site_domain": site.domain,
-                            "workdate": workdate,
-                        },
-                        ensure_ascii=False,
-                    )
+            user_data_list = await site_oper.async_get_userdata_by_domain(
+                domain=site.domain, workdate=workdate
+            )
 
-                # 格式化用户数据
-                result = {
-                    "success": True,
-                    "site_id": site_id,
-                    "site_name": site.name,
-                    "site_domain": site.domain,
-                    "workdate": workdate,
-                    "data_count": len(user_data_list),
-                    "user_data": [],
+            if not user_data_list:
+                return json.dumps(
+                    {
+                        "success": False,
+                        "message": f"站点 {site.name} ({site.domain}) 暂无用户数据",
+                        "site_id": site_id,
+                        "site_name": site.name,
+                        "site_domain": site.domain,
+                        "workdate": workdate,
+                    },
+                    ensure_ascii=False,
+                )
+
+            # 格式化用户数据
+            result = {
+                "success": True,
+                "site_id": site_id,
+                "site_name": site.name,
+                "site_domain": site.domain,
+                "workdate": workdate,
+                "data_count": len(user_data_list),
+                "user_data": [],
+            }
+
+            for user_data in user_data_list:
+                # 格式化上传/下载量（转换为可读格式）
+                upload_gb = user_data.upload / (1024**3) if user_data.upload else 0
+                download_gb = (
+                    user_data.download / (1024**3) if user_data.download else 0
+                )
+                seeding_size_gb = (
+                    user_data.seeding_size / (1024**3)
+                    if user_data.seeding_size
+                    else 0
+                )
+                leeching_size_gb = (
+                    user_data.leeching_size / (1024**3)
+                    if user_data.leeching_size
+                    else 0
+                )
+
+                seeding_preview, seeding_count, seeding_truncated = _preview_list(
+                    user_data.seeding_info
+                )
+                unread_preview, unread_count, unread_truncated = _preview_list(
+                    user_data.message_unread_contents
+                )
+
+                user_data_dict = {
+                    "domain": user_data.domain,
+                    "name": user_data.name,
+                    "username": user_data.username,
+                    "userid": user_data.userid,
+                    "user_level": user_data.user_level,
+                    "join_at": user_data.join_at,
+                    "bonus": user_data.bonus,
+                    "upload": user_data.upload,
+                    "upload_gb": round(upload_gb, 2),
+                    "download": user_data.download,
+                    "download_gb": round(download_gb, 2),
+                    "ratio": round(user_data.ratio, 2) if user_data.ratio else 0,
+                    "seeding": int(user_data.seeding) if user_data.seeding else 0,
+                    "leeching": int(user_data.leeching)
+                    if user_data.leeching
+                    else 0,
+                    "seeding_size": user_data.seeding_size,
+                    "seeding_size_gb": round(seeding_size_gb, 2),
+                    "leeching_size": user_data.leeching_size,
+                    "leeching_size_gb": round(leeching_size_gb, 2),
+                    "seeding_info_count": seeding_count,
+                    "seeding_info": seeding_preview,
+                    "seeding_info_truncated": seeding_truncated,
+                    "message_unread": user_data.message_unread,
+                    "message_unread_contents_count": unread_count,
+                    "message_unread_contents": unread_preview,
+                    "message_unread_contents_truncated": unread_truncated,
+                    "err_msg": user_data.err_msg,
+                    "updated_day": user_data.updated_day,
+                    "updated_time": user_data.updated_time,
                 }
+                result["user_data"].append(user_data_dict)
 
-                for user_data in user_data_list:
-                    # 格式化上传/下载量（转换为可读格式）
-                    upload_gb = user_data.upload / (1024**3) if user_data.upload else 0
-                    download_gb = (
-                        user_data.download / (1024**3) if user_data.download else 0
-                    )
-                    seeding_size_gb = (
-                        user_data.seeding_size / (1024**3)
-                        if user_data.seeding_size
-                        else 0
-                    )
-                    leeching_size_gb = (
-                        user_data.leeching_size / (1024**3)
-                        if user_data.leeching_size
-                        else 0
-                    )
+            # 如果有多条数据，只返回最新的（按更新时间排序）
+            if len(result["user_data"]) > 1:
+                result["user_data"].sort(
+                    key=lambda x: (
+                        x.get("updated_day", ""),
+                        x.get("updated_time", ""),
+                    ),
+                    reverse=True,
+                )
+                result["message"] = (
+                    f"找到 {len(result['user_data'])} 条数据，显示最新的一条"
+                )
+                result["user_data"] = [result["user_data"][0]]
 
-                    seeding_preview, seeding_count, seeding_truncated = _preview_list(
-                        user_data.seeding_info
-                    )
-                    unread_preview, unread_count, unread_truncated = _preview_list(
-                        user_data.message_unread_contents
-                    )
-
-                    user_data_dict = {
-                        "domain": user_data.domain,
-                        "name": user_data.name,
-                        "username": user_data.username,
-                        "userid": user_data.userid,
-                        "user_level": user_data.user_level,
-                        "join_at": user_data.join_at,
-                        "bonus": user_data.bonus,
-                        "upload": user_data.upload,
-                        "upload_gb": round(upload_gb, 2),
-                        "download": user_data.download,
-                        "download_gb": round(download_gb, 2),
-                        "ratio": round(user_data.ratio, 2) if user_data.ratio else 0,
-                        "seeding": int(user_data.seeding) if user_data.seeding else 0,
-                        "leeching": int(user_data.leeching)
-                        if user_data.leeching
-                        else 0,
-                        "seeding_size": user_data.seeding_size,
-                        "seeding_size_gb": round(seeding_size_gb, 2),
-                        "leeching_size": user_data.leeching_size,
-                        "leeching_size_gb": round(leeching_size_gb, 2),
-                        "seeding_info_count": seeding_count,
-                        "seeding_info": seeding_preview,
-                        "seeding_info_truncated": seeding_truncated,
-                        "message_unread": user_data.message_unread,
-                        "message_unread_contents_count": unread_count,
-                        "message_unread_contents": unread_preview,
-                        "message_unread_contents_truncated": unread_truncated,
-                        "err_msg": user_data.err_msg,
-                        "updated_day": user_data.updated_day,
-                        "updated_time": user_data.updated_time,
-                    }
-                    result["user_data"].append(user_data_dict)
-
-                # 如果有多条数据，只返回最新的（按更新时间排序）
-                if len(result["user_data"]) > 1:
-                    result["user_data"].sort(
-                        key=lambda x: (
-                            x.get("updated_day", ""),
-                            x.get("updated_time", ""),
-                        ),
-                        reverse=True,
-                    )
-                    result["message"] = (
-                        f"找到 {len(result['user_data'])} 条数据，显示最新的一条"
-                    )
-                    result["user_data"] = [result["user_data"][0]]
-
-                return json.dumps(result, ensure_ascii=False, indent=2)
+            return json.dumps(result, ensure_ascii=False, indent=2)
 
         except Exception as e:
             error_message = f"查询站点用户数据失败: {str(e)}"

app/agent/tools/impl/query_sites.py

@@ -6,6 +6,7 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
 from app.db.site_oper import SiteOper
 from app.log import logger
 
@@ -13,8 +14,6 @@ from app.log import logger
 class QuerySitesInput(BaseModel):
     """查询站点工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        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",
@@ -26,8 +25,15 @@ class QuerySitesInput(BaseModel):
 
 class QuerySitesTool(MoviePilotTool):
     name: str = "query_sites"
-    description: str = "Query site status and list all configured sites. Shows site name, domain, status, priority, and basic configuration. Site priority (pri): smaller values have higher priority (e.g., pri=1 has higher priority than pri=10)."
-    require_admin: bool = True
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Site,
+    ]
+    description: str = (
+        "Query site status and list configured sites. Non-admin users receive a safe view "
+        "that omits sensitive fields: cookie, token, API key and RSS URL. "
+        "Site priority (pri): smaller values have higher priority (e.g., pri=1 has higher priority than pri=10)."
+    )
     args_schema: Type[BaseModel] = QuerySitesInput
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
@@ -51,6 +57,7 @@ class QuerySitesTool(MoviePilotTool):
     ) -> str:
         logger.info(f"执行工具: {self.name}, 参数: status={status}, name={name}")
         try:
+            is_admin = await self.is_admin_user()
             site_oper = SiteOper()
             # 获取所有站点（按优先级排序）
             sites = await site_oper.async_list()
@@ -76,11 +83,25 @@ class QuerySitesTool(MoviePilotTool):
                         "url": s.url,
                         "pri": s.pri,
                         "is_active": s.is_active,
-                        "cookie": s.cookie,
                         "downloader": s.downloader,
+                        "ua": s.ua,
                         "proxy": s.proxy,
+                        "filter": s.filter,
+                        "render": s.render,
+                        "public": s.public,
+                        "note": s.note,
+                        "limit_interval": s.limit_interval,
+                        "limit_count": s.limit_count,
+                        "limit_seconds": s.limit_seconds,
                         "timeout": s.timeout,
                     }
+                    if is_admin:
+                        simplified.update({
+                            "rss": s.rss,
+                            "cookie": s.cookie,
+                            "apikey": s.apikey,
+                            "token": s.token,
+                        })
                     simplified_sites.append(simplified)
                 result_json = json.dumps(simplified_sites, ensure_ascii=False, indent=2)
                 return result_json

app/agent/tools/impl/query_subscribe_history.py

@@ -6,8 +6,8 @@ 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.subscribehistory import SubscribeHistory
+from app.agent.tools.tags import ToolTag
+from app.db.subscribehistory_oper import SubscribeHistoryOper
 from app.log import logger
 from app.schemas.types import media_type_to_agent
 
@@ -17,8 +17,6 @@ PAGE_SIZE = 20
 class QuerySubscribeHistoryInput(BaseModel):
     """查询订阅历史工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
     media_type: Optional[str] = Field(
         "all", description="Allowed values: movie, tv, all"
     )
@@ -33,6 +31,10 @@ class QuerySubscribeHistoryInput(BaseModel):
 
 class QuerySubscribeHistoryTool(MoviePilotTool):
     name: str = "query_subscribe_history"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Subscription,
+    ]
     description: str = "Query subscription history records. Shows completed subscriptions with their details including name, type, rating, completion date, and other subscription information. Supports filtering by media type and name. Supports pagination with 20 records per page."
     args_schema: Type[BaseModel] = QuerySubscribeHistoryInput
 
@@ -69,88 +71,87 @@ class QuerySubscribeHistoryTool(MoviePilotTool):
             if media_type not in ["all", "movie", "tv"]:
                 return f"错误：无效的媒体类型 '{media_type}'，支持的类型：'movie', 'tv', 'all'"
 
-            # 获取数据库会话
-            async with AsyncSessionFactory() as db:
-                if name:
-                    # 有名称过滤时，获取足够多的记录在内存中过滤，不分页
-                    fetch_count = 500
-                    if media_type == "all":
-                        movie_history = await SubscribeHistory.async_list_by_type(
-                            db, mtype="movie", page=1, count=fetch_count
-                        )
-                        tv_history = await SubscribeHistory.async_list_by_type(
-                            db, mtype="tv", page=1, count=fetch_count
-                        )
-                        all_history = list(movie_history) + list(tv_history)
-                        all_history.sort(key=lambda x: x.date or "", reverse=True)
-                    else:
-                        all_history = list(
-                            await SubscribeHistory.async_list_by_type(
-                                db, mtype=media_type, page=1, count=fetch_count
-                            )
-                        )
-
-                    # 按名称过滤
-                    name_lower = name.lower()
-                    filtered_history = [
-                        record
-                        for record in all_history
-                        if record.name and name_lower in record.name.lower()
-                    ]
-
-                    if not filtered_history:
-                        return "未找到相关订阅历史记录"
-
-                    # 名称过滤时直接返回所有匹配结果，不分页
-                    simplified_records = self._simplify_records(filtered_history)
-                    result_json = json.dumps(
-                        simplified_records, ensure_ascii=False, indent=2
+            subscribe_history_oper = SubscribeHistoryOper()
+            if name:
+                # 有名称过滤时，获取足够多的记录在内存中过滤，不分页
+                fetch_count = 500
+                if media_type == "all":
+                    movie_history = await subscribe_history_oper.async_list_by_type(
+                        mtype="movie", page=1, count=fetch_count
                     )
-                    return result_json
+                    tv_history = await subscribe_history_oper.async_list_by_type(
+                        mtype="tv", page=1, count=fetch_count
+                    )
+                    all_history = list(movie_history) + list(tv_history)
+                    all_history.sort(key=lambda x: x.date or "", reverse=True)
                 else:
-                    # 无名称过滤时，直接利用数据库分页
-                    if media_type == "all":
-                        movie_history = await SubscribeHistory.async_list_by_type(
-                            db, mtype="movie", page=1, count=page * PAGE_SIZE
-                        )
-                        tv_history = await SubscribeHistory.async_list_by_type(
-                            db, mtype="tv", page=1, count=page * PAGE_SIZE
-                        )
-                        all_history = list(movie_history) + list(tv_history)
-                        all_history.sort(key=lambda x: x.date or "", reverse=True)
-                        filtered_history = all_history
-                    else:
-                        filtered_history = list(
-                            await SubscribeHistory.async_list_by_type(
-                                db, mtype=media_type, page=1, count=page * PAGE_SIZE
-                            )
+                    all_history = list(
+                        await subscribe_history_oper.async_list_by_type(
+                            mtype=media_type, page=1, count=fetch_count
                         )
+                    )
+
+                # 按名称过滤
+                name_lower = name.lower()
+                filtered_history = [
+                    record
+                    for record in all_history
+                    if record.name and name_lower in record.name.lower()
+                ]
 
                 if not filtered_history:
                     return "未找到相关订阅历史记录"
 
-                # 分页切片
-                total_count = len(filtered_history)
-                start = (page - 1) * PAGE_SIZE
-                end = start + PAGE_SIZE
-                page_records = filtered_history[start:end]
-
-                if not page_records:
-                    return f"第 {page} 页没有数据。"
-
-                simplified_records = self._simplify_records(page_records)
+                # 名称过滤时直接返回所有匹配结果，不分页
+                simplified_records = self._simplify_records(filtered_history)
                 result_json = json.dumps(
                     simplified_records, ensure_ascii=False, indent=2
                 )
-
-                has_more = total_count > end
-                payload_msg = f"第 {page} 页，当前页 {len(simplified_records)} 条结果。"
-                if has_more:
-                    payload_msg += (
-                        f" 可能有更多数据，可使用 page={page + 1} 获取下一页。"
+                return result_json
+            else:
+                # 无名称过滤时，直接利用数据库分页
+                if media_type == "all":
+                    movie_history = await subscribe_history_oper.async_list_by_type(
+                        mtype="movie", page=1, count=page * PAGE_SIZE
+                    )
+                    tv_history = await subscribe_history_oper.async_list_by_type(
+                        mtype="tv", page=1, count=page * PAGE_SIZE
+                    )
+                    all_history = list(movie_history) + list(tv_history)
+                    all_history.sort(key=lambda x: x.date or "", reverse=True)
+                    filtered_history = all_history
+                else:
+                    filtered_history = list(
+                        await subscribe_history_oper.async_list_by_type(
+                            mtype=media_type, page=1, count=page * PAGE_SIZE
+                        )
                     )
 
-                return f"{payload_msg}\n\n{result_json}"
+            if not filtered_history:
+                return "未找到相关订阅历史记录"
+
+            # 分页切片
+            total_count = len(filtered_history)
+            start = (page - 1) * PAGE_SIZE
+            end = start + PAGE_SIZE
+            page_records = filtered_history[start:end]
+
+            if not page_records:
+                return f"第 {page} 页没有数据。"
+
+            simplified_records = self._simplify_records(page_records)
+            result_json = json.dumps(
+                simplified_records, ensure_ascii=False, indent=2
+            )
+
+            has_more = total_count > end
+            payload_msg = f"第 {page} 页，当前页 {len(simplified_records)} 条结果。"
+            if has_more:
+                payload_msg += (
+                    f" 可能有更多数据，可使用 page={page + 1} 获取下一页。"
+                )
+
+            return f"{payload_msg}\n\n{result_json}"
         except Exception as e:
             logger.error(f"查询订阅历史失败: {e}", exc_info=True)
             return f"查询订阅历史时发生错误: {str(e)}"
@@ -169,6 +170,9 @@ class QuerySubscribeHistoryTool(MoviePilotTool):
                 "tmdbid": record.tmdbid,
                 "doubanid": record.doubanid,
                 "bangumiid": record.bangumiid,
+                "anilistid": record.anilistid,
+                "media_source": record.media_source,
+                "media_id": record.media_id,
                 "poster": record.poster,
                 "vote": record.vote,
                 "total_episode": record.total_episode,

app/agent/tools/impl/query_subscribe_shares.py

@@ -6,7 +6,8 @@ from typing import Optional, Type
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
-from app.helper.subscribe import SubscribeHelper
+from app.agent.tools.tags import ToolTag
+from app.helper.server import MoviePilotServerHelper
 from app.log import logger
 
 MAX_PAGE_SIZE = 50
@@ -14,7 +15,6 @@ MAX_PAGE_SIZE = 50
 
 class QuerySubscribeSharesInput(BaseModel):
     """查询订阅分享工具的输入参数模型"""
-    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     name: Optional[str] = Field(None, description="Filter shares by media name (partial match, optional)")
     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, max: 50)")
@@ -26,6 +26,10 @@ class QuerySubscribeSharesInput(BaseModel):
 
 class QuerySubscribeSharesTool(MoviePilotTool):
     name: str = "query_subscribe_shares"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Subscription,
+    ]
     description: str = "Query shared subscriptions from other users. Shows popular subscriptions shared by the community with filtering and pagination support."
     args_schema: Type[BaseModel] = QuerySubscribeSharesInput
 
@@ -68,8 +72,7 @@ class QuerySubscribeSharesTool(MoviePilotTool):
             # 订阅分享是外部列表型结果，限制单页大小能降低工具上下文占用。
             count = min(count, MAX_PAGE_SIZE)
 
-            subscribe_helper = SubscribeHelper()
-            shares = await subscribe_helper.async_get_shares(
+            shares = await MoviePilotServerHelper.async_get_subscribe_shares(
                 name=name,
                 page=page,
                 count=count,
@@ -94,6 +97,9 @@ class QuerySubscribeSharesTool(MoviePilotTool):
                     "tmdbid": share.get("tmdbid"),
                     "doubanid": share.get("doubanid"),
                     "bangumiid": share.get("bangumiid"),
+                    "anilistid": share.get("anilistid"),
+                    "media_source": share.get("media_source"),
+                    "media_id": share.get("media_id"),
                     "poster": share.get("poster"),
                     "vote": share.get("vote"),
                     "share_title": share.get("share_title"),