更新 version.py

修复Pydantic验证错误：QueryTransferHistoryInput的explanation字段为必需，但用户未提供。
修改了74个工具文件，将explanation字段从必需改为可选，默认值为None。

.dockerignore

@@ -73,6 +73,7 @@ test_*
 build/
 dist/
 *.egg-info/
+rust/**/target/
 
 # Docker
 Dockerfile*
@@ -81,4 +82,4 @@ docker-compose*
 
 # Other
 app.ico
-frozen.spec
+frozen.spec

.github/workflows/beta.yml

@@ -46,7 +46,7 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build Image
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: docker/Dockerfile
@@ -56,5 +56,5 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha, scope=${{ github.workflow }}-docker
-          cache-to: type=gha, scope=${{ github.workflow }}-docker
+          cache-from: type=gha,scope=moviepilot-docker,version=2
+          cache-to: type=gha,scope=moviepilot-docker,mode=max,version=2

.github/workflows/build.yml

@@ -56,7 +56,7 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build Image
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: docker/Dockerfile
@@ -66,8 +66,8 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha, scope=${{ github.workflow }}-docker
-          cache-to: type=gha, scope=${{ github.workflow }}-docker
+          cache-from: type=gha,scope=moviepilot-docker,version=2
+          cache-to: type=gha,scope=moviepilot-docker,mode=max,version=2
 
       - name: Generate Changelog
         id: changelog

.github/workflows/issues.yml

@@ -2,13 +2,138 @@ name: Close inactive issues
 on:
  workflow_dispatch:
 
+ issues:
+   types: [opened, edited]
+
  schedule:
    # Github Action 只支持 UTC 时间。
    # '0 18 * * *' 对应 UTC 时间的 18:00，也就是中国时区 (UTC+8) 的第二天凌晨 02:00。
    - cron: "0 18 * * *"
 
 jobs:
+ label-opened-issue:
+   if: github.event_name == 'issues'
+   runs-on: ubuntu-latest
+   permissions:
+     issues: write
+   steps:
+     - uses: actions/github-script@v7
+       with:
+         script: |
+           const issue = context.payload.issue;
+           const title = issue.title || '';
+           const body = issue.body || '';
+           const currentLabels = (issue.labels || []).map((label) => label.name);
+
+           // 网页 Issue Form 已经会自动带模板 labels；这里只兜底处理
+           // API 创建或异常路径产生的无 label issue，避免重复补标。
+           if (currentLabels.length > 0) {
+             core.info(`Issue #${issue.number} already has labels: ${currentLabels.join(', ')}`);
+             return;
+           }
+
+           const hasAllMarkers = (markers) => markers.every((marker) => body.includes(marker));
+           const labelRules = [
+             {
+               label: 'bug',
+               titlePrefix: '[错误报告]:',
+               markers: ['### 当前程序版本', '### 运行环境', '### 问题类型', '### 问题描述'],
+             },
+             {
+               label: 'feature request',
+               titlePrefix: '[Feature Request]:',
+               markers: ['### 当前程序版本', '### 运行环境', '### 功能改进类型', '### 功能改进'],
+             },
+             {
+               label: 'RFC',
+               titlePrefix: '[RFC]',
+               markers: ['### 背景 or 问题', '### 目标 & 方案简述'],
+             },
+           ];
+
+           const matched = labelRules.find((rule) => (
+             title.startsWith(rule.titlePrefix) || hasAllMarkers(rule.markers)
+           ));
+
+           if (!matched) {
+             core.info(`Issue #${issue.number} does not match known issue templates.`);
+             return;
+           }
+
+           await github.rest.issues.addLabels({
+             owner: context.repo.owner,
+             repo: context.repo.repo,
+             issue_number: issue.number,
+             labels: [matched.label],
+           });
+           core.info(`Added label "${matched.label}" to issue #${issue.number}.`);
+
+ label-unlabeled-issues:
+   if: github.event_name != 'issues'
+   runs-on: ubuntu-latest
+   permissions:
+     issues: write
+   steps:
+     - uses: actions/github-script@v7
+       with:
+         script: |
+           const labelRules = [
+             {
+               label: 'bug',
+               titlePrefix: '[错误报告]:',
+               markers: ['### 当前程序版本', '### 运行环境', '### 问题类型', '### 问题描述'],
+             },
+             {
+               label: 'feature request',
+               titlePrefix: '[Feature Request]:',
+               markers: ['### 当前程序版本', '### 运行环境', '### 功能改进类型', '### 功能改进'],
+             },
+             {
+               label: 'RFC',
+               titlePrefix: '[RFC]',
+               markers: ['### 背景 or 问题', '### 目标 & 方案简述'],
+             },
+           ];
+
+           const hasAllMarkers = (body, markers) => markers.every((marker) => body.includes(marker));
+           const getMatchedRule = (issue) => {
+             const title = issue.title || '';
+             const body = issue.body || '';
+             return labelRules.find((rule) => (
+               title.startsWith(rule.titlePrefix) || hasAllMarkers(body, rule.markers)
+             ));
+           };
+
+           // Search API 支持 no:label 查询；issues.listForRepo 的 labels=none
+           // 会被当作名为 none 的标签，不能用于扫描无 label issue。
+           const query = `repo:${context.repo.owner}/${context.repo.repo} is:issue is:open no:label`;
+           for await (const response of github.paginate.iterator(github.rest.search.issuesAndPullRequests, {
+             q: query,
+             per_page: 100,
+           })) {
+             for (const issue of response.data) {
+               if (issue.pull_request) {
+                 continue;
+               }
+
+               const matched = getMatchedRule(issue);
+               if (!matched) {
+                 continue;
+               }
+
+               await github.rest.issues.addLabels({
+                 owner: context.repo.owner,
+                 repo: context.repo.repo,
+                 issue_number: issue.number,
+                 labels: [matched.label],
+               });
+               core.info(`Added label "${matched.label}" to issue #${issue.number}.`);
+             }
+           }
+
  close-issues:
+   if: github.event_name != 'issues'
+   needs: label-unlabeled-issues
    runs-on: ubuntu-latest
    permissions:
      issues: write
@@ -30,4 +155,4 @@ jobs:
          # 排除带有RFC标签的issue
          exempt-issue-labels: "RFC"
          operations-per-run: 500
-         repo-token: ${{ secrets.GITHUB_TOKEN }}
+         repo-token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -6,6 +6,7 @@
 build/
 cython_cache/
 dist/
+rust/**/target/
 nginx/
 test.py
 safety_report.txt
@@ -21,6 +22,7 @@ config/user.db*
 config/sites/**
 config/agent/
 config/logs/
+config/plugins/
 config/temp/
 config/cache/
 .runtime/

.pylintrc

@@ -5,38 +5,30 @@ init-hook='import sys; sys.path.append(".")'
 # 忽略的文件和目录
 ignore=.git,__pycache__,.venv,build,dist,tests,docs
 
+# 通过 `pylint app/` 检查主程序时不扫描内置插件目录，
+# 插件依赖和动态模型较多，容易产生与主程序无关的误报。
+ignore-paths=^app/plugins(/|$)
+
 # 并行作业数量
 jobs=0
 
 [MESSAGES CONTROL]
-# 只关注错误级别的问题，禁用警告、约定和重构建议
-# E = Error (错误) - 会导致构建失败
-# W = Warning (警告) - 仅显示，不会失败
-# R = Refactor (重构建议) - 仅显示，不会失败
-# C = Convention (约定) - 仅显示，不会失败
-# I = Information (信息) - 仅显示，不会失败
-
-# 禁用大部分警告、约定和重构建议，只保留错误和重要警告
+# 只启用确定性较强的严重问题检查，避免 SQLAlchemy、FastAPI 依赖注入、
+# 第三方 SDK 等动态对象被 Pylint 推断成误报。
 disable=all
-enable=E,
-       syntax-error,
+enable=syntax-error,
        undefined-variable,
        used-before-assignment,
+       possibly-used-before-assignment,
        unreachable,
        return-outside-function,
        yield-outside-function,
        continue-in-finally,
        nonlocal-without-binding,
        undefined-loop-variable,
-       redefined-builtin,
-       not-callable,
-       assignment-from-no-return,
-       no-value-for-parameter,
-       too-many-function-args,
-       unexpected-keyword-arg,
-       redundant-keyword-arg,
        import-error,
-       relative-beyond-top-level
+       relative-beyond-top-level,
+       no-name-in-module
 
 [REPORTS]
 # 设置报告格式
@@ -80,4 +72,6 @@ ignore-imports=yes
 
 [TYPECHECK]
 # 生成缺失成员提示的类列表
-generated-members=requests.packages.urllib3
+generated-members=requests.packages.urllib3
+# app.helper.sites 会主动隐藏模块属性枚举，避免误报 no-name-in-module
+ignored-modules=app.helper.sites

AGENTS.md

@@ -1,152 +1,103 @@
-# MoviePilot AI Agent Guide
+# AGENTS.md
 
-This file defines the default behavior for AI agents working in the MoviePilot repository. Unless a deeper directory provides another `AGENTS.md`, these rules apply to the entire repo.
+This file is the primary instruction set for all AI agents and LLMs working in this repository. Local documentation takes precedence over general training data. You must follow this file and the rule documents it references.
 
-## 1. Project Scope
+---
 
-- This repository contains the MoviePilot backend, CLI, MCP/API, Docker assets, and AI skills.
-- The backend is based on FastAPI, with most code under `app/`.
-- Frontend source code is not in this repository. The frontend source repository is `MoviePilot-Frontend`.
-- This repository also includes the local CLI, database migrations, developer docs, tests, Docker scripts, and AI skills.
+## Task-to-Documentation Mapping
 
-## 2. Working Principles
+Before executing any task, identify the domain and load the corresponding document.
 
-- Read the relevant implementation, tests, and docs before changing code. Do not infer behavior from directory names alone.
-- Prefer the smallest correct change. Reuse existing functions, patterns, and naming whenever possible.
-- Do not perform unrelated large refactors, mass renames, or formatting-only cleanup.
-- Before adding a new abstraction, check whether it is actually reusable. If the logic fits well inside an existing function, class, or flow, keep it there.
-- The worktree may contain user changes. Do not revert, overwrite, or reorganize changes you do not fully understand.
-- Default to writing conclusions, validation results, and risk notes in Chinese unless the user asks otherwise.
+### Architectural Decisions
+* **Primary Reference:** `docs/rules/05-architecture.md`
+* **Required Constraints:** Respect layer boundaries and dependency flow. Do not introduce circular dependencies. Verify the correct layer for any new capability before implementing.
 
-## 3. Key Directories
+### Business Logic and Design Patterns
+* **Primary Reference:** `docs/rules/04-design-patterns.md`
+* **Required Constraints:** Use the project's established Module, Chain, Event, and Oper structural patterns. Do not introduce abstractions the project has not adopted.
 
-- `app/api/endpoints/`: HTTP entrypoints. Handles auth, parameters, responses, and simple CRUD.
-- `app/chain/`: Business orchestration layer for search, recognition, subscriptions, downloads, messaging flows, and similar use cases.
-- `app/modules/`: Dynamically loaded system modules. Encapsulates pluggable downloaders, media servers, message channels, and other backend capabilities.
-- `app/helper/`: Reusable low-level helper logic. Not a place for full business orchestration.
-- `app/core/config.py`: Environment variables, deployment parameters, and startup-level settings.
-- `app/schemas/types.py`: Shared enums and types such as `SystemConfigKey` and module categories.
-- `app/db/`: Database models, sessions, and `*_oper.py` data access wrappers.
-- `moviepilot`: Local CLI entrypoint and help text.
-- `database/versions/`: Alembic migration scripts.
-- `docs/`: CLI, MCP/API, and development workflow documentation.
-- `skills/`: AI agent skills and related scripts.
-- `tests/`: Pytest tests and a few manual test scripts.
-- `config/`, `.moviepilot.env`, and `*.db`: Local config or runtime data. Do not modify or commit them unless the user explicitly asks for it.
+### Coding Standards and Style
+* **Primary Reference:** `docs/rules/06-code-styles.md`
+* **Required Constraints:** Match the style of the surrounding file. Type annotations, Pydantic models, and async/await usage must all conform to the documented standards.
 
-## 4. Layering And Access Boundaries
+### Identifiers and Naming
+* **Primary Reference:** `docs/rules/07-naming-conventions.md`
+* **Required Constraints:** All filenames, class names, function names, and constants must follow the project's taxonomy. No arbitrary abbreviations or mixed casing styles.
 
-### API / Endpoint Layer
+### Comments and Documentation
+* **Primary Reference:** `docs/rules/08-comment-styles.md`
+* **Required Constraints:** All public classes and methods require Chinese docstrings. Comments must explain the *why*, not restate the code.
+* **⚠️ MANDATORY GATE:** Code that is missing proper Chinese docstrings on public interfaces is **REJECTED** at review. No exceptions.
 
-- Endpoints should only handle HTTP concerns: auth, parameter parsing, response models, streaming adaptation, and simple input validation.
-- Simple list, detail, toggle, settings read/write, and pure CRUD endpoints may directly call `app/db/` or an existing `helper`.
-- If the logic coordinates multiple modules, triggers events, touches caches, or combines search, recognition, subscription, or download workflows, move it into `chain`.
-- Prefer adding new endpoints to an existing domain file. Create a new endpoint file only when introducing a new top-level resource domain.
-- After adding a new endpoint, register it in `app/api/apiv1.py`.
+### External Communication and Interfaces
+* **Primary Reference:** `docs/rules/09-external-response.md`
+* **Required Constraints:** All third-party HTTP requests must go through `RequestUtils`. Response formats must use the project's standard schemas. Error handling must follow the per-layer conventions.
 
-### Chain Layer
+### Data and Persistence
+* **Primary Reference:** `docs/rules/10-data-and-persistent.md`
+* **Required Constraints:** Any database model change requires a matching Alembic migration. Runtime configuration must be managed via `SystemConfigKey` + `SystemConfigOper`. Raw string keys are forbidden.
 
-- `chain` is the business orchestration layer shared by API, CLI, message interaction, agents, schedulers, and similar entrypoints.
-- `chain` is responsible for composing `module`, `helper`, `db`, events, caches, and other stable `chain` capabilities.
-- Inside `chain`, prefer calling module capabilities through `run_module()` or `async_run_module()`. Only use `ModuleManager` or similar helpers directly when you truly need to enumerate modules, inspect instances, or run health checks.
-- `chain` should focus on use cases and workflows. It should not hold low-level protocol details, HTTP request objects, or page-specific parameter assembly.
-- Before adding a new `chain`, ask whether this is a reusable business use case shared by multiple entrypoints, or a flow that coordinates multiple modules or resources. If it is just short logic for one endpoint, do not create a new `chain`.
-- `chain` may call other `chain` classes when reusing stable domain logic, but avoid introducing new circular dependencies.
+### Quality and Security
+* **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.
 
-### Module Layer
+### 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.
 
-- `module` is the pluggable capability layer discovered and loaded by `ModuleManager`.
-- Put logic in `module` when it represents a new downloader, media server, message channel, recognition backend, filtering backend, file-management backend, or any other capability that needs lifecycle management, priority, configuration switches, or independent testing.
-- New modules should follow the existing base-class contract and implement or align with `init_module()`, `init_setting()`, `get_name()`, `get_type()`, `get_subtype()`, `get_priority()`, `test()`, and `stop()`.
-- A `module` should focus on one backend or one capability implementation. It should return domain results, not HTTP responses, and should not depend on endpoint auth or FastAPI request objects.
-- `chain -> module` is the intended main direction. The repository contains a small number of historical `module -> chain` usages. Do not expand that pattern in new code. If a module needs shared business logic, prefer moving that logic up into `chain` or down into `helper`.
-- Do not add direct `module -> module` coupling for new code. Cross-module orchestration should be handled by `chain`.
+---
 
-### Helper Layer
+## Agent Execution Rules
 
-- `helper` is for reusable low-level support logic such as path handling, config aggregation, site index loading, protocol wrappers, rate limiting, cache helpers, and page parsing.
-- Add a new `helper` only when the logic is reused in multiple places, or when it is clearly a standalone low-level concern.
-- If logic is used only by a single `chain` or a single `module`, prefer keeping it in the original file instead of turning `helper` into a dumping ground.
-- If the code needs configuration switches, runtime loading, priorities, independent test entrypoints, or multi-implementation dispatch, it is probably a `module`, not a `helper`.
-- `helper` must not become another orchestration layer. Full business workflows still belong in `chain`.
+### Pre-Flight Check
 
-### Preferred Call Directions
+Before generating any code or proposing changes, you must:
 
-- Preferred direction: `endpoint/CLI/agent/command -> chain -> module/helper/db`
-- Allowed direction: `chain -> chain`, as long as the reused logic is stable and does not introduce cycles.
-- Cautious direction: `endpoint -> db/model/oper/helper`, only for simple queries, simple CRUD, or input normalization.
-- Avoid for new code: `module -> chain`, `module -> module`, `helper -> chain`, `helper -> endpoint`.
+1. Identify the task domain (architecture / business logic / coding style / naming / comments / external interfaces / data / quality).
+2. Load the corresponding document from `docs/rules/`.
+3. Explicitly verify that your proposed solution does not violate the following three mandatory constraints:
+   - **Naming Conventions (07):** Are all files, classes, functions, and constants named correctly?
+   - **Architecture Boundaries (05):** Is the code placed in the correct layer? Are all call directions valid?
+   - **Comment Standards (08):** Do all new public classes and methods include Chinese docstrings?
 
-## 5. Where New Capabilities Should Go
+### Implementation Guidelines
 
-- Scenario: adding a new business workflow such as search, recognition, subscription, download orchestration, or message interaction.
-  Action: prefer `app/chain/` so API, CLI, agents, and schedulers can share the same orchestration logic.
-- Scenario: adding a new downloader, media server, message channel, or other pluggable backend integration.
-  Action: put it in `app/modules/`. If this introduces a new module category or subtype, also check `app/schemas/types.py` and related schemas.
-- Scenario: adding a new public HTTP API.
-  Action: put it in `app/api/endpoints/`, register it in `app/api/apiv1.py`, and add auth, schemas, docs, and tests. Move complex logic into `chain`.
-- Scenario: adding a new low-level utility, parser, config reader, or protocol wrapper.
-  Action: put it in `app/helper/`, but only if it is not a one-off implementation and not a full business use case.
-- Scenario: adding a deployment-level, environment-level, or startup-time config such as ports, paths, proxies, switches, keys, or third-party service addresses.
-  Action: put it in `ConfigModel` or `Settings` inside `app/core/config.py`.
-- Scenario: adding a runtime business config, user-editable rule, or persistent system option.
-  Action: prefer `SystemConfigKey` plus `SystemConfigOper`. Do not scatter raw string keys.
-- Scenario: a config change should automatically reload a long-lived object.
-  Action: add `CONFIG_WATCH`, `on_config_changed()`, and `get_reload_name()` where appropriate on the related `chain`, `module`, `helper`, or manager class.
-- Scenario: adding a few dozen lines of private logic inside one `chain` or `module`.
-  Action: prefer a private function or private method in the same file. Do not create a new `helper` by default.
+* **Pattern Adherence:** Avoid generic boilerplate. If `04-design-patterns.md` defines a project-level pattern for a scenario, you are required to use it.
+* **Documentation Standards:** Docstring style for any new function or module must match `08-comment-styles.md`.
+* **⚠️ MANDATORY GATE:** Public classes, methods, and functions without proper Chinese docstrings are **REJECTED**. No exceptions.
+* **Command Reliance:** Only suggest commands listed in `03-commands.md`. Do not rely on inferred tool defaults.
+* **Minimal Change Principle:** Prefer the smallest correct change. Do not perform unrelated refactors, mass renames, or formatting-only cleanup.
+* **Output Language:** Summaries, validation results, and risk notes default to Chinese unless the user requests otherwise.
 
-## 6. Code And Comment Requirements
+### Conflict Resolution
 
-- Preserve the existing code style. Do not introduce a new abstraction layer without a clear payoff.
-- The repository already uses short docstrings for many public classes and methods. For new public classes and methods, follow the local style of the surrounding file.
-- Comments and docstrings should default to Chinese. If the surrounding file is already consistently in English, match the local style.
-- Comments should explain why the code is written that way and what non-obvious constraints exist, such as edge cases, compatibility reasons, call ordering, cache or reload semantics, and external system limitations.
-- Do not write line-by-line translation comments. Do not comment obvious assignments, branches, or straightforward calls.
-- For complex notes, place the comment above the code block instead of using long end-of-line comments.
-- When changing code, update or remove stale comments so the documentation stays aligned with the implementation.
-- Do not add TODO or FIXME without context. Only keep one if it is genuinely useful and cannot be addressed as part of the current task.
-- Do not add noisy comments like "change starts here", "change ends here", or "this is important".
+If existing code appears to contradict the documentation:
 
-## 7. Dependency And Environment Conventions
+1. Stop implementation immediately.
+2. Identify the specific file and line of the contradiction.
+3. Prompt the user: "The documentation in `[File]` requires Pattern A, but the current implementation uses Pattern B. Which is the current standard?"
 
-- Target Python version is `3.11+`. Current CI uses Python `3.12`.
-- The dependency source file is `requirements.in`.
-- `requirements.txt` is the lock file generated by `pip-compile requirements.in`. Do not maintain it manually.
-- Install dependencies with `pip install -r requirements.txt`.
-- When adding or upgrading dependencies:
-  1. Update `requirements.in`
-  2. Run `pip-compile requirements.in`
-  3. Run the relevant tests and security checks
+---
 
-## 8. Coupled Updates
+## Coupled Update Rules
 
-- When fixing a bug, prefer adding a test that reproduces it. When adding a feature, prefer the smallest useful test coverage.
-- When changing CLI behavior, also check and update `moviepilot`, `docs/cli.md`, and related tests.
-- When changing MCP or REST API behavior, exposed tools, or AI interaction behavior, also check and update `docs/mcp-api.md`, related `skills/*/SKILL.md` files or scripts, and related tests.
-- When changing development workflow, dependency management, or security-check procedures, also update `docs/development-setup.md`.
-- When changing database structure, add an Alembic migration under `database/versions/`. Do not update models without a migration.
-- When changing user-visible config, defaults, or initialization flow, also check related docs, help text, setup or init flows, and tests.
-- When adding a new skill, follow the existing `skills/<name>/SKILL.md` structure, keep the YAML front matter, and prefer script paths relative to the `SKILL.md` file.
+When modifying the following, you must also update the listed artifacts:
 
-## 9. Validation Requirements
+| Changed Content | Must Also Update |
+|---|---|
+| CLI behavior | `moviepilot` entrypoint, `docs/cli.md`, related tests |
+| MCP / REST API, exposed tools | `docs/mcp-api.md`, `skills/*/SKILL.md`, related tests |
+| Dev workflow, dependency management, security checks | `docs/development-setup.md` |
+| Database model schema | New Alembic migration under `database/versions/` |
+| User-visible config or init flow | Related docs, help text, setup/init flows, tests |
+| New skill | Follow `skills/<name>/SKILL.md` structure, keep YAML front matter |
 
-- Run at least the tests directly related to the change, for example `pytest tests/test_xxx.py`.
-- If the change affects common modules, startup flow, CLI, or agent runtime behavior, expand the validation scope.
-- After Python code changes, at minimum ensure the change does not introduce new error-level issues in `pylint app/`.
-- When changing CLI behavior, validate the relevant help output such as `moviepilot help` or the specific subcommand help.
-- When changing dependencies, also run `pip-compile requirements.in` and `safety check -r requirements.txt --policy-file=safety.policy.yml`.
-- If the task only changes documentation, explicitly say that tests were not run. Do not claim checks that were not executed.
+---
 
-## 10. Commit And Release Conventions
+## Primary Entry Point
 
-- Only create a commit when the user explicitly asks for one.
-- Prefer Conventional Commits such as `feat: ...`, `fix: ...`, and `docs: ...`.
-- This is not just stylistic. The release workflow uses Conventional Commits to categorize changelog entries.
-- Do not casually change version numbers, release settings, or Docker release flow unless the task explicitly involves them.
+For the full documentation map and cross-references, refer to:
 
-## 11. Output Requirements
+**[Documentation Hub Index](./docs/rules/README.md)**
 
-- Result summaries should focus on three things: what changed, how it was validated, and what risks remain.
-- Do not write vague summaries. Do not describe unexecuted checks as completed.
-- If there is compatibility impact, config migration risk, or user-data risk, call it out explicitly.
+*Last Updated: 2026-05-25*

README.md

@@ -56,6 +56,23 @@ MCP工具API文档：详见 [docs/mcp-api.md](docs/mcp-api.md)
 
 开发环境准备与本地源码运行说明：[`docs/development-setup.md`](docs/development-setup.md)
 
+本地开发启用 Rust 加速扩展，需先安装 Rust toolchain 并确保 `cargo` 可用；未安装时项目会自动使用 Python 实现：
+
+```shell
+cargo --version
+python -m pip install "maturin>=1.9,<2"
+python -m maturin develop --release --manifest-path rust/moviepilot_rust/Cargo.toml
+python -c "from app.utils import rust_accel; print(rust_accel.is_available())"
+```
+
+如果输出 `True`，说明当前开发环境已经加载 `moviepilot_rust`。重新修改 Rust 代码后再次执行 `python -m maturin develop --release --manifest-path rust/moviepilot_rust/Cargo.toml` 即可更新本地扩展。
+
+需要本地评估 Rust 加速效果时，可运行：
+
+```shell
+python scripts/benchmark_rust_accel.py --loops 20 --repeat 5
+```
+
 插件开发说明：<https://wiki.movie-pilot.org/zh/plugindev>
 
 ## 相关项目

app/agent/__init__.py

@@ -4,7 +4,7 @@ import re
 import traceback
 import uuid
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timedelta
 from enum import Enum
 from typing import Any, Callable, Dict, List, Optional
 
@@ -43,10 +43,11 @@ from app.agent.runtime import agent_runtime_manager
 from app.agent.tools.factory import MoviePilotToolFactory
 from app.chain import ChainBase
 from app.core.config import settings
+from app.core.event import eventmanager
 from app.log import logger
-from app.schemas import Notification, NotificationType
+from app.schemas import AgentLLMProviderEventData, AgentTokensUsageEventData, Notification, NotificationType
 from app.schemas.message import ChannelCapabilityManager, ChannelCapability
-from app.schemas.types import MessageChannel
+from app.schemas.types import ChainEventType, EventType, MessageChannel
 from app.utils.identity import SYSTEM_INTERNAL_USER_ID
 
 
@@ -58,22 +59,36 @@ def _finish_processing_status(status: Optional[dict], user_id: Optional[str] = N
     """结束入站消息的渠道处理状态。"""
     if not status:
         return
-    try:
-        channel = MessageChannel(status.get("channel"))
-    except Exception:
-        return
-    try:
-        AgentChain().run_module(
-            "mark_message_processing_finished",
-            channel=channel,
-            source=status.get("source"),
-            userid=status.get("userid") or user_id,
-            message_id=status.get("message_id"),
-            chat_id=status.get("chat_id"),
-            status=status,
-        )
-    except Exception as err:
-        logger.debug(f"结束Agent消息处理状态失败: {err}")
+    AgentChain().finish_message_processing_status(
+        status=status,
+        userid=user_id,
+    )
+
+
+async def _async_start_processing_status(task: "_MessageTask") -> Optional[dict]:
+    """
+    在 Agent worker 中启动渠道处理状态。
+    渠道启动可能触发外部 API，同步实现需切到线程池避免阻塞事件循环。
+    """
+    if not task.channel:
+        return None
+
+    def _start() -> Optional[dict]:
+        """在线程池中通过统一 Chain 接口启动处理状态。"""
+        try:
+            return AgentChain().start_message_processing_status(
+                channel=MessageChannel(task.channel),
+                source=task.source,
+                userid=task.user_id,
+                message_id=task.original_message_id,
+                chat_id=task.original_chat_id,
+                text=task.message,
+            )
+        except Exception as err:
+            logger.debug(f"启动Agent消息处理状态失败: {err}")
+            return None
+
+    return await run_in_threadpool(_start)
 
 
 async def _async_finish_processing_status(
@@ -205,6 +220,8 @@ class ReplyMode(str, Enum):
 
 HEARTBEAT_SESSION_PREFIX = "__agent_heartbeat_"
 UNSUPPORTED_IMAGE_INPUT_MESSAGE = "当前模型不支持图片输入，请更换支持图片输入的模型，或在系统设置中关闭图片输入支持后重试。"
+AGENT_EXECUTION_ERROR_PREFIX = "智能助手执行失败"
+AGENT_EXECUTION_ERROR_MESSAGE = "智能助手执行失败，请稍后重试。"
 
 
 class MoviePilotAgent:
@@ -240,6 +257,9 @@ class MoviePilotAgent:
         self._tool_context: Dict[str, object] = {}
         self._streamed_output = ""
         self._session_usage = _SessionUsageSnapshot()
+        self._llm_runtime_config: Optional[Dict[str, Any]] = None
+        self._llm_provider_selection: Dict[str, Any] = {}
+        self._agent_started_at: Optional[datetime] = None
 
         # 流式token管理
         self.stream_handler = StreamingHandler()
@@ -325,6 +345,40 @@ class MoviePilotAgent:
             )
         return self._session_usage.to_dict(self.session_id)
 
+    def _send_agent_tokens_usage_event(
+            self,
+            *,
+            success: bool,
+            error: Optional[str] = None,
+    ) -> None:
+        """
+        广播本次 Agent 执行的 token 聚合用量，供配额类插件异步记录。
+        """
+        try:
+            selection = self._llm_provider_selection or {}
+            event_data = AgentTokensUsageEventData(
+                session_id=self.session_id,
+                selected_provider_id=selection.get("selected_provider_id"),
+                selected_provider_name=selection.get("selected_provider_name"),
+                provider=selection.get("provider") or settings.LLM_PROVIDER,
+                base_url=selection.get("base_url") or settings.LLM_BASE_URL,
+                model=self._session_usage.model or selection.get("model") or settings.LLM_MODEL,
+                input_tokens=self._session_usage.total_input_tokens,
+                output_tokens=self._session_usage.total_output_tokens,
+                total_tokens=self._session_usage.total_tokens,
+                model_call_count=self._session_usage.model_call_count,
+                success=success,
+                error=error,
+                started_at=self._agent_started_at.strftime("%Y-%m-%d %H:%M:%S")
+                if self._agent_started_at
+                else None,
+                finished_at=datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                source=selection.get("source") or "agent",
+            )
+            eventmanager.send_event(EventType.AgentTokensUsage, event_data)
+        except Exception as err:
+            logger.debug(f"广播 Agent Tokens 用量事件失败: {err}")
+
     @property
     def is_background(self) -> bool:
         """
@@ -372,12 +426,113 @@ class MoviePilotAgent:
             return False
 
     @staticmethod
-    async def _initialize_llm(streaming: bool = False):
+    def _get_event_value(event_data: Any, key: str, default: Any = None) -> Any:
+        """
+        从链式事件数据中兼容读取 Pydantic 模型或普通字典字段。
+        """
+        if isinstance(event_data, dict):
+            return event_data.get(key, default)
+        return getattr(event_data, key, default)
+
+    @staticmethod
+    def _set_event_value(event_data: Any, key: str, value: Any) -> None:
+        """
+        向链式事件数据中兼容写入 Pydantic 模型或普通字典字段。
+        """
+        if isinstance(event_data, dict):
+            event_data[key] = value
+        else:
+            setattr(event_data, key, value)
+
+    @classmethod
+    def _clean_optional_text(cls, value: Any) -> Optional[str]:
+        """
+        标准化事件返回的可选文本字段，空字符串按未返回处理。
+        """
+        if value is None:
+            return None
+        text = str(value).strip()
+        return text or None
+
+    async def _resolve_llm_runtime_config(self) -> Dict[str, Any]:
+        """
+        通过链式事件解析本次 Agent 可用的 LLM 运行时配置。
+
+        若没有插件返回 selected_provider_id，则沿用系统配置，保持既有行为。
+        """
+        if self._llm_runtime_config is not None:
+            return self._llm_runtime_config
+
+        event_data = AgentLLMProviderEventData(
+            provider=settings.LLM_PROVIDER,
+            model=settings.LLM_MODEL,
+            api_key=settings.LLM_API_KEY,
+            base_url=settings.LLM_BASE_URL,
+            base_url_preset=settings.LLM_BASE_URL_PRESET,
+            thinking_level=None,
+        )
+        selected_event = await eventmanager.async_send_event(
+            ChainEventType.AgentLLMProvider,
+            event_data,
+        )
+        resolved_data = selected_event.event_data if selected_event else event_data
+
+        provider = (
+                self._clean_optional_text(self._get_event_value(resolved_data, "provider"))
+                or settings.LLM_PROVIDER
+        )
+        model = (
+                self._clean_optional_text(self._get_event_value(resolved_data, "model"))
+                or settings.LLM_MODEL
+        )
+        api_key = (
+                self._clean_optional_text(self._get_event_value(resolved_data, "api_key"))
+                or settings.LLM_API_KEY
+        )
+        base_url = (
+                self._clean_optional_text(self._get_event_value(resolved_data, "base_url"))
+                or settings.LLM_BASE_URL
+        )
+        base_url_preset = (
+                self._clean_optional_text(self._get_event_value(resolved_data, "base_url_preset"))
+                or settings.LLM_BASE_URL_PRESET
+        )
+        thinking_level = self._clean_optional_text(
+            self._get_event_value(resolved_data, "thinking_level")
+        )
+        selected_provider_id = self._clean_optional_text(
+            self._get_event_value(resolved_data, "selected_provider_id")
+        )
+        selected_provider_name = self._clean_optional_text(
+            self._get_event_value(resolved_data, "selected_provider_name")
+        )
+        source = self._clean_optional_text(self._get_event_value(resolved_data, "source"))
+
+        self._llm_provider_selection = {
+            "selected_provider_id": selected_provider_id,
+            "selected_provider_name": selected_provider_name,
+            "provider": provider,
+            "base_url": base_url,
+            "model": model,
+            "source": source,
+        }
+        self._llm_runtime_config = {
+            "provider": provider,
+            "model": model,
+            "api_key": api_key,
+            "base_url": base_url,
+            "base_url_preset": base_url_preset,
+            "thinking_level": thinking_level,
+        }
+        return self._llm_runtime_config
+
+    async def _initialize_llm(self, streaming: bool = False):
         """
         初始化 LLM
         :param streaming: 是否启用流式输出
         """
-        return await LLMHelper.get_llm(streaming=streaming)
+        runtime_config = await self._resolve_llm_runtime_config()
+        return await LLMHelper.get_llm(streaming=streaming, **runtime_config)
 
     @staticmethod
     def _extract_text_content(content) -> str:
@@ -481,6 +636,77 @@ class MoviePilotAgent:
             )
         )
 
+    @staticmethod
+    def _payload_error_message(payload: Any) -> str:
+        """
+        从 SDK 返回的结构化错误体里提取 message 字段。
+        许多 OpenAI-compatible 服务会把真正原因放在 body.error.message 中。
+        """
+        if isinstance(payload, dict):
+            error = payload.get("error")
+            if isinstance(error, dict) and error.get("message"):
+                return str(error["message"])
+            for key in ("message", "detail", "error_description"):
+                if payload.get(key):
+                    return str(payload[key])
+        return ""
+
+    @staticmethod
+    def _sanitize_execution_error_message(message: str) -> str:
+        """
+        清理执行错误中的密钥和尾部长说明，避免把敏感字段或 SDK 调参文档直接发给用户。
+        """
+        sanitized = re.sub(r"\s+", " ", str(message or "")).strip()
+        if settings.LLM_API_KEY:
+            sanitized = sanitized.replace(settings.LLM_API_KEY, "***")
+        sanitized = re.sub(
+            r"(?i)(api[_-]?key\s*[:=]\s*)([^\s,;]+)",
+            r"\1***",
+            sanitized,
+        )
+        sanitized = re.sub(
+            r"(?i)authorization\s*:\s*bearer\s+[^\s,;]+",
+            "Authorization: ***",
+            sanitized,
+        )
+        for marker in (
+                " Tune or disable via ",
+                " See also ",
+                " Traceback ",
+                " - Traceback ",
+        ):
+            if marker in sanitized:
+                sanitized = sanitized.split(marker, 1)[0].strip()
+        return sanitized
+
+    @classmethod
+    def _primary_exception_message(cls, error: Exception) -> str:
+        """
+        从异常对象中抽取最主要的错误消息。
+        优先使用结构化 message，其次回退到异常字符串，保持用户回复直接反映真实失败原因。
+        """
+        candidates = [
+            getattr(error, "message", None),
+            cls._payload_error_message(getattr(error, "body", None)),
+            str(error),
+        ]
+        for candidate in candidates:
+            message = cls._sanitize_execution_error_message(candidate)
+            if message:
+                return message
+        return ""
+
+    @classmethod
+    def _friendly_execution_error_message(cls, error: Exception) -> str:
+        """
+        将 Agent 执行异常转换为用户可读消息。
+        回复只携带主错误信息，完整 traceback 保留在日志中排查。
+        """
+        message = cls._primary_exception_message(error)
+        if not message:
+            return AGENT_EXECUTION_ERROR_MESSAGE
+        return f"{AGENT_EXECUTION_ERROR_PREFIX}: {message}"
+
     async def _dispatch_execution_notice(self, message: str) -> None:
         """
         将执行层可预期的失败转成用户可读提示。
@@ -663,7 +889,10 @@ class MoviePilotAgent:
             messages.append(HumanMessage(content=content))
 
             # 执行推理
-            await self._execute_agent(messages)
+            result = await self._execute_agent(messages)
+            if isinstance(result, tuple) and result:
+                return result[0]
+            return result
 
         except Exception as e:
             error_message = f"处理消息时发生错误: {str(e)}"
@@ -725,6 +954,11 @@ class MoviePilotAgent:
         - 渠道不支持消息编辑：非流式 LLM + ainvoke，完成后发送最终回复
         - 渠道支持消息编辑：流式 LLM + astream，实时推送 token
         """
+        execution_success = False
+        execution_error: Optional[str] = None
+        self._agent_started_at = datetime.now()
+        self._llm_runtime_config = None
+        self._llm_provider_selection = {}
         try:
             # Agent运行配置
             agent_config = {
@@ -858,11 +1092,14 @@ class MoviePilotAgent:
                 user_id=self.user_id,
                 messages=agent.get_state(agent_config).values.get("messages", []),
             )
+            execution_success = True
 
         except asyncio.CancelledError:
             logger.info(f"Agent执行被取消: session_id={self.session_id}")
+            execution_error = "任务已取消"
             return "任务已取消", {}
         except Exception as e:
+            execution_error = str(e)
             if self._messages_have_image_input(messages) and self._is_unsupported_image_input_error(e):
                 logger.warning(
                     f"当前模型不支持图片输入，已向用户发送友好提示: {e}"
@@ -870,8 +1107,14 @@ class MoviePilotAgent:
                 await self._dispatch_execution_notice(UNSUPPORTED_IMAGE_INPUT_MESSAGE)
                 return UNSUPPORTED_IMAGE_INPUT_MESSAGE, {}
             logger.error(f"Agent执行失败: {e} - {traceback.format_exc()}")
-            return str(e), {}
+            friendly_message = self._friendly_execution_error_message(e)
+            await self._dispatch_execution_notice(friendly_message)
+            return friendly_message, {}
         finally:
+            self._send_agent_tokens_usage_event(
+                success=execution_success,
+                error=execution_error,
+            )
             # 确保停止流式输出
             await self.stream_handler.stop_streaming()
 
@@ -952,6 +1195,11 @@ class AgentManager:
         self._session_queues: Dict[str, asyncio.Queue] = {}
         # 每个会话的worker任务
         self._session_workers: Dict[str, asyncio.Task] = {}
+        # 每个会话最后活动时间，用于回收空闲 Agent 实例
+        self._session_last_used: Dict[str, tuple[str, datetime]] = {}
+        self._idle_cleanup_task: Optional[asyncio.Task] = None
+        self._idle_session_ttl = timedelta(hours=24)
+        self._idle_cleanup_interval = 60 * 60
 
     def get_session_status(self, session_id: str) -> dict[str, Any]:
         """获取会话当前模型与 token 使用状态。"""
@@ -984,33 +1232,85 @@ class AgentManager:
         )
         return status
 
-    @staticmethod
-    async def initialize():
+    async def initialize(self):
         """
         初始化管理器
         """
         memory_manager.initialize()
+        if self._idle_cleanup_task and not self._idle_cleanup_task.done():
+            return
+        self._idle_cleanup_task = asyncio.create_task(self._cleanup_idle_sessions())
 
     async def close(self):
         """
         关闭管理器
         """
+        if self._idle_cleanup_task:
+            self._idle_cleanup_task.cancel()
+            try:
+                await self._idle_cleanup_task
+            except asyncio.CancelledError:
+                pass
+            self._idle_cleanup_task = None
         await memory_manager.close()
         # 取消所有会话worker
-        for task in self._session_workers.values():
+        for task in list(self._session_workers.values()):
             task.cancel()
         # 等待所有worker结束
-        for session_id, task in self._session_workers.items():
+        for session_id, task in list(self._session_workers.items()):
             try:
                 await task
             except asyncio.CancelledError:
                 pass
         self._session_workers.clear()
         self._session_queues.clear()
-        for agent in self.active_agents.values():
+        self._session_last_used.clear()
+        for agent in list(self.active_agents.values()):
             await agent.cleanup()
         self.active_agents.clear()
 
+    def _record_session_activity(self, session_id: str, user_id: str) -> None:
+        """
+        记录会话最近活动时间，供空闲会话清理任务判断是否可释放资源。
+        """
+        self._session_last_used[session_id] = (user_id, datetime.now())
+
+    def _is_session_busy(self, session_id: str) -> bool:
+        """
+        判断会话是否仍有正在执行的 worker 或待处理消息，避免误清理活跃会话。
+        """
+        worker = self._session_workers.get(session_id)
+        if worker and not worker.done():
+            return True
+        queue = self._session_queues.get(session_id)
+        return bool(queue and not queue.empty())
+
+    def _expired_idle_sessions(self) -> list[tuple[str, str]]:
+        """
+        收集已经超过空闲时间且当前不忙的会话。
+        """
+        expire_before = datetime.now() - self._idle_session_ttl
+        expired = []
+        for session_id, (user_id, last_used) in list(self._session_last_used.items()):
+            if last_used < expire_before and not self._is_session_busy(session_id):
+                expired.append((session_id, user_id))
+        return expired
+
+    async def _cleanup_idle_sessions(self) -> None:
+        """
+        周期性清理长时间没有新消息的 Agent 会话，避免长期运行后实例持续累积。
+        """
+        while True:
+            try:
+                await asyncio.sleep(self._idle_cleanup_interval)
+                for session_id, user_id in self._expired_idle_sessions():
+                    await self.clear_session(session_id=session_id, user_id=user_id)
+                    logger.info(f"已清理空闲Agent会话: session_id={session_id}")
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"清理空闲Agent会话失败: {e}")
+
     async def process_message(
             self,
             session_id: str,
@@ -1023,7 +1323,6 @@ class AgentManager:
             username: str = None,
             original_message_id: Optional[str] = None,
             original_chat_id: Optional[str] = None,
-            processing_status: Optional[dict] = None,
             reply_mode: ReplyMode = ReplyMode.DISPATCH,
     ) -> str:
         """
@@ -1041,9 +1340,9 @@ class AgentManager:
             username=username,
             original_message_id=original_message_id,
             original_chat_id=original_chat_id,
-            processing_status=processing_status,
             reply_mode=reply_mode,
         )
+        self._record_session_activity(session_id, user_id)
 
         # 获取或创建会话队列
         if session_id not in self._session_queues:
@@ -1096,13 +1395,12 @@ class AgentManager:
                     break
 
                 try:
+                    await self._start_task_processing_status(task)
                     await self._process_message_internal(task)
                 except Exception as e:
                     logger.error(f"处理会话 {session_id} 的消息失败: {e}")
                 finally:
-                    await _async_finish_processing_status(
-                        task.processing_status, task.user_id
-                    )
+                    await self._finish_task_processing_status(task)
                     queue.task_done()
 
         except asyncio.CancelledError:
@@ -1117,6 +1415,23 @@ class AgentManager:
             ):
                 self._session_queues.pop(session_id, None)
 
+    @staticmethod
+    async def _start_task_processing_status(task: _MessageTask) -> None:
+        """
+        在 Agent worker 真正开始处理消息时启动渠道处理状态。
+        """
+        if task.processing_status:
+            return
+        task.processing_status = await _async_start_processing_status(task)
+
+    @staticmethod
+    async def _finish_task_processing_status(task: _MessageTask) -> None:
+        """
+        在 Agent worker 完成或异常后结束本条消息的渠道处理状态。
+        """
+        await _async_finish_processing_status(task.processing_status, task.user_id)
+        task.processing_status = None
+
     async def _process_message_internal(self, task: _MessageTask):
         """
         实际处理单条消息
@@ -1193,6 +1508,7 @@ class AgentManager:
         """
         清空会话
         """
+        self._session_last_used.pop(session_id, None)
         # 取消该会话的worker
         if session_id in self._session_workers:
             self._session_workers[session_id].cancel()
@@ -1200,7 +1516,7 @@ class AgentManager:
                 await self._session_workers[session_id]
             except asyncio.CancelledError:
                 pass
-            await self._session_workers.pop(session_id, None)
+            self._session_workers.pop(session_id, None)
 
         # 清理队列
         self._session_queues.pop(session_id, None)

app/agent/callback/__init__.py

@@ -307,7 +307,10 @@ class StreamingHandler:
                 or tool_kwargs.get("path"),
             )
         if tool_name == "execute_command":
-            return "command", tool_kwargs.get("command")
+            return (
+                "command",
+                tool_kwargs.get("command") or tool_kwargs.get("session_id"),
+            )
         if tool_name == "ask_user_choice":
             return "interaction", tool_kwargs.get("message")
         if tool_name.startswith("search_") or tool_name in {"get_search_results"}:

app/agent/llm/capability.py

@@ -9,11 +9,12 @@ import subprocess
 from abc import ABC
 from io import BytesIO
 from pathlib import Path
-from typing import Dict, Optional
+from typing import Any, Dict, Optional
 from uuid import uuid4
 
 from app.core.config import settings
 from app.log import logger
+from app.utils.http import RequestUtils
 
 
 class AgentCapabilityProvider(ABC):
@@ -411,6 +412,160 @@ class MiMoAudioProvider(OpenAIChatAudioProvider):
         return model
 
 
+class MiniMaxAudioProvider(OpenAIChatAudioProvider):
+    """MiniMax 音频 provider，语音合成使用官方 T2A HTTP 接口。"""
+
+    name = "minimax"
+    DISPLAY_NAME = "MiniMax"
+    DEFAULT_BASE_URL = "https://api.minimaxi.com/v1"
+    DEFAULT_STT_MODEL = "MiniMax-M2.7"
+    DEFAULT_TTS_MODEL = "speech-2.8-turbo"
+    DEFAULT_VOICE = "Chinese (Mandarin)_Lyrical_Voice"
+    AUDIO_INPUT_DATA_URL = True
+    SUPPORTED_TTS_MODELS = frozenset(
+        {
+            "speech-2.8-hd",
+            "speech-2.8-turbo",
+            "speech-2.6-hd",
+            "speech-2.6-turbo",
+            "speech-02-hd",
+            "speech-02-turbo",
+            "speech-01-hd",
+            "speech-01-turbo",
+        }
+    )
+
+    def _build_client(self, api_key: str, base_url: Optional[str]):
+        """构建 MiniMax OpenAI 兼容客户端，兼容用户误填 Anthropic 端点的情况。"""
+        from openai import OpenAI
+
+        return OpenAI(
+            api_key=api_key,
+            base_url=self._normalize_api_base_url(base_url),
+            max_retries=3,
+        )
+
+    @classmethod
+    def _normalize_api_base_url(cls, base_url: Optional[str]) -> str:
+        """归一化 MiniMax API 基础 URL，确保后续可以拼接 OpenAI/T2A 路径。"""
+        normalized = (base_url or cls.DEFAULT_BASE_URL).strip().rstrip("/")
+        if normalized.endswith("/t2a_v2"):
+            normalized = normalized[: -len("/t2a_v2")]
+        for suffix in ("/anthropic/v1", "/openai/v1"):
+            if normalized.endswith(suffix):
+                return normalized[: -len(suffix)] + "/v1"
+        if not normalized.endswith("/v1"):
+            normalized = f"{normalized}/v1"
+        return normalized
+
+    @classmethod
+    def _build_t2a_url(cls, base_url: Optional[str]) -> str:
+        """生成 MiniMax 同步 T2A 接口地址。"""
+        return f"{cls._normalize_api_base_url(base_url)}/t2a_v2"
+
+    def _normalize_stt_model(self) -> str:
+        """将非 MiniMax 的默认转写模型名兜底为 MiniMax 对话模型。"""
+        model = (settings.AUDIO_INPUT_MODEL or "").strip()
+        if not model or model.lower().startswith(("gpt-", "mimo-")):
+            return self.DEFAULT_STT_MODEL
+        return model
+
+    def _normalize_tts_model(self) -> str:
+        """将非 MiniMax 语音模型兜底为官方 T2A 模型。"""
+        model = (settings.AUDIO_OUTPUT_MODEL or "").strip().lower()
+        if model in self.SUPPORTED_TTS_MODELS:
+            return model
+        return self.DEFAULT_TTS_MODEL
+
+    def _normalize_voice_id(self) -> str:
+        """将其他 provider 的默认音色兜底为 MiniMax 中文系统音色。"""
+        voice_id = (settings.AUDIO_OUTPUT_VOICE or "").strip()
+        if not voice_id or voice_id in {"alloy", "mimo_default"}:
+            return self.DEFAULT_VOICE
+        return voice_id
+
+    @staticmethod
+    def _decode_audio_payload(audio_data: str) -> bytes:
+        """解析 MiniMax T2A 返回的音频数据，优先按官方 hex 格式处理。"""
+        normalized = "".join((audio_data or "").split())
+        try:
+            return bytes.fromhex(normalized)
+        except ValueError:
+            return base64.b64decode(audio_data)
+
+    @staticmethod
+    def _extract_minimax_error(data: dict[str, Any]) -> Optional[str]:
+        """提取 MiniMax base_resp 错误信息，成功响应返回 None。"""
+        base_resp = data.get("base_resp") or {}
+        status_code = base_resp.get("status_code")
+        if status_code in (None, 0, "0"):
+            return None
+        status_msg = base_resp.get("status_msg") or "unknown error"
+        return f"{status_code}: {status_msg}"
+
+    def synthesize_speech(self, text: str) -> Optional[Path]:
+        """调用 MiniMax T2A HTTP 接口合成语音文件。"""
+        if not text:
+            return None
+
+        try:
+            api_key, base_url = self._output_credentials()
+            if not api_key:
+                raise ValueError("音频输出 provider 未配置 API Key")
+            response = RequestUtils(
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                },
+                proxies=settings.PROXY or {},
+                timeout=60,
+            ).post_res(
+                url=self._build_t2a_url(base_url),
+                json={
+                    "model": self._normalize_tts_model(),
+                    "text": text,
+                    "stream": False,
+                    "language_boost": "auto",
+                    "output_format": "hex",
+                    "voice_setting": {
+                        "voice_id": self._normalize_voice_id(),
+                        "speed": 1,
+                        "vol": 1,
+                        "pitch": 0,
+                    },
+                    "audio_setting": {
+                        "sample_rate": 32000,
+                        "bitrate": 128000,
+                        "format": "opus",
+                        "channel": 1,
+                    },
+                },
+            )
+            if not response:
+                raise ValueError("MiniMax T2A 请求无响应")
+            if response.status_code >= 400:
+                raise ValueError(f"MiniMax T2A HTTP {response.status_code}")
+
+            result = response.json()
+            minimax_error = self._extract_minimax_error(result)
+            if minimax_error:
+                raise ValueError(f"MiniMax T2A 返回错误: {minimax_error}")
+
+            audio_data = ((result.get("data") or {}).get("audio") or "").strip()
+            if not audio_data:
+                raise ValueError("MiniMax T2A 响应中没有音频数据")
+
+            voice_dir = settings.TEMP_PATH / "voice"
+            voice_dir.mkdir(parents=True, exist_ok=True)
+            output_path = voice_dir / f"{uuid4().hex}.opus"
+            output_path.write_bytes(self._decode_audio_payload(audio_data))
+            return output_path
+        except Exception as err:
+            logger.error(f"音频输出合成失败: provider={self.name}, error={err}")
+            return None
+
+
 class AgentCapabilityManager:
     """Agent 能力统一入口。"""
 
@@ -420,6 +575,7 @@ class AgentCapabilityManager:
         OpenAIAudioProvider.name: OpenAIAudioProvider(),
         OpenAIChatAudioProvider.name: OpenAIChatAudioProvider(),
         MiMoAudioProvider.name: MiMoAudioProvider(),
+        MiniMaxAudioProvider.name: MiniMaxAudioProvider(),
     }
 
     @classmethod

app/agent/llm/helper.py

@@ -32,29 +32,87 @@ class LLMTestTimeout(TimeoutError):
 def _patch_gemini_thought_signature():
     """
     修复 langchain-google-genai 中 Gemini 2.5 思考模型的 thought_signature 兼容问题。
-    langchain-google-genai 的 _is_gemini_3_or_later() 仅检查 "gemini-3"，
-    导致 Gemini 2.5 思考模型（如 gemini-2.5-flash、gemini-2.5-pro）在工具调用时
-    缺少 thought_signature 而报错 400。
-    此补丁将检查范围扩展到 Gemini 2.5 模型。
+
+    问题 1：_is_gemini_3_or_later() 仅检查 "gemini-3"，不包含 Gemini 2.5 模型，
+    导致 _parse_chat_history 的 thought_signature 强制注入逻辑被跳过。
+
+    问题 2：强制注入逻辑使用 first_fc_seen 标志，只给每个 model 消息中
+    第一个缺少 thought_signature 的 function_call 补 dummy，后续并行
+    function_call 仍缺失签名，导致 Gemini API 返回 400。
+
+    此补丁同时修复以上两个问题。
     """
     try:
         import langchain_google_genai.chat_models as _cm
 
+        # 检查版本：需要 >= 4.0 才支持 _is_gemini_3_or_later
+        try:
+            from importlib.metadata import version
+            _version = version("langchain-google-genai") or ""
+        except Exception:
+            _version = ""
+        try:
+            _major = int(_version.split(".")[0]) if _version else 0
+        except (ValueError, TypeError):
+            _major = 0
+        if _major < 4:
+            logger.error(
+                f"langchain-google-genai 版本 {_version or '未知'} 过旧，"
+                f"不支持 Gemini 2.5+ 模型的 thought_signature 处理，"
+                f"请升级到 4.2.3+：pip install langchain-google-genai~=4.2.3"
+            )
+            return
+
         # 仅在未修补时执行
         if getattr(_cm, "_thought_signature_patched", False):
             return
 
+        if not hasattr(_cm, "_is_gemini_3_or_later"):
+            logger.error(
+                "langchain-google-genai 缺少 _is_gemini_3_or_later，"
+                "无法修补 thought_signature 兼容性，请检查包版本"
+            )
+            return
+
+        # 补丁 1：扩展 _is_gemini_3_or_later，使 Gemini 2.5 模型也能触发
+        # _parse_chat_history 中的 thought_signature 强制注入逻辑
         def _patched_is_gemini_3_or_later(model_name: str) -> bool:
             if not model_name:
                 return False
             name = model_name.lower().replace("models/", "")
-            # Gemini 2.5 思考模型也需要 thought_signature 支持
             return "gemini-3" in name or "gemini-2.5" in name
 
         _cm._is_gemini_3_or_later = _patched_is_gemini_3_or_later
+
+        # 补丁 2：修复 _parse_chat_history 中 first_fc_seen 只修复第一个
+        # function_call 的问题。用 wrapper 在原函数返回后，确保所有 model
+        # 消息中所有 function_call 都带有 thought_signature。
+        _original_parse_chat_history = _cm._parse_chat_history
+
+        def _patched_parse_chat_history(*args, **kwargs):
+            result = _original_parse_chat_history(*args, **kwargs)
+            system_instruction, formatted_messages = result
+
+            # 从参数中提取 model 名称
+            model = kwargs.get("model")
+            if model is None and len(args) >= 4:
+                model = args[3]
+
+            if model and _patched_is_gemini_3_or_later(model):
+                dummy = _cm.DUMMY_THOUGHT_SIGNATURE
+                for content_msg in formatted_messages:
+                    if content_msg.role == "model":
+                        for part in content_msg.parts or []:
+                            if part.function_call and not part.thought_signature:
+                                part.thought_signature = dummy
+
+            return result
+
+        _cm._parse_chat_history = _patched_parse_chat_history
         _cm._thought_signature_patched = True
         logger.debug(
-            "已修补 langchain-google-genai thought_signature 兼容性（覆盖 Gemini 2.5 模型）"
+            "已修补 langchain-google-genai thought_signature 兼容性"
+            "（覆盖 Gemini 2.5 模型 + 修复并行 function_call 签名缺失）"
         )
     except Exception as e:
         logger.warning(f"修补 langchain-google-genai thought_signature 失败: {e}")

app/agent/llm/provider.py

@@ -105,6 +105,7 @@ class LLMProviderManager(metaclass=Singleton):
     _MODELS_DEV_URL = "https://models.dev/api.json"
     _MODELS_DEV_BUNDLED_PATH = Path(__file__).with_name("models.json")
     _MODELS_DEV_CACHE_TTL = 7 * 24 * 60 * 60
+    _AUTH_SESSION_DONE_RETENTION = 300
     _CHATGPT_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
     _CHATGPT_ISSUER = "https://auth.openai.com"
     _CHATGPT_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"
@@ -183,6 +184,33 @@ class LLMProviderManager(metaclass=Singleton):
                 Path(settings.TEMP_PATH) / "llm_provider_models_dev_cache.json"
         )
 
+    def _cleanup_auth_sessions_locked(self, now: Optional[float] = None) -> None:
+        """
+        清理过期或已完成一段时间的临时授权会话。
+
+        调用方必须已经持有 `_lock`，这样 `_pending_sessions` 与
+        `_oauth_state_index` 能保持一致，避免 state 残留。
+        """
+        now = time.time() if now is None else now
+        expired_session_ids = []
+        for session_id, session in self._pending_sessions.items():
+            expires_at = session.expires_at or session.created_at + 600
+            if session.status == "pending":
+                if expires_at <= now:
+                    expired_session_ids.append(session_id)
+            elif expires_at + self._AUTH_SESSION_DONE_RETENTION <= now:
+                expired_session_ids.append(session_id)
+
+        if not expired_session_ids:
+            return
+
+        expired_session_ids_set = set(expired_session_ids)
+        for session_id in expired_session_ids:
+            self._pending_sessions.pop(session_id, None)
+        for state, session_id in list(self._oauth_state_index.items()):
+            if session_id in expired_session_ids_set:
+                self._oauth_state_index.pop(state, None)
+
     @staticmethod
     def _builtin_provider_specs() -> tuple[ProviderSpec, ...]:
         """
@@ -672,6 +700,88 @@ class LLMProviderManager(metaclass=Singleton):
                 description="腾讯兼容端点。",
                 sort_order=170,
             ),
+            ProviderSpec(
+                id="china-unicom",
+                name="中国联通",
+                runtime="openai_compatible",
+                default_base_url="https://aigw-gzgy2.cucloud.cn:8443/v1",
+                base_url_presets=(
+                    url_preset(
+                        id="china-unicom-coding-openai",
+                        label="Coding Plan / OpenAI",
+                        value="https://aigw-gzgy2.cucloud.cn:8443/v1",
+                        model_list_strategy="manual",
+                    ),
+                    url_preset(
+                        id="china-unicom-coding-anthropic",
+                        label="Coding Plan / Anthropic",
+                        value="https://aigw-gzgy2.cucloud.cn:8443",
+                        runtime="anthropic_compatible",
+                        model_list_strategy="manual",
+                    ),
+                ),
+                base_url_editable=True,
+                api_key_hint="填写联通云 AISP / Coding Plan 专属 API Key；模型名称请按控制台可用模型 ID 手动填写。",
+                supports_model_refresh=False,
+                model_list_strategy="manual",
+                description="联通云 AISP Coding Plan 兼容端点，支持 OpenAI 与 Anthropic 协议地址预设。",
+                sort_order=172,
+            ),
+            ProviderSpec(
+                id="china-mobile",
+                name="中国移动",
+                runtime="openai_compatible",
+                default_base_url="https://ecloud.10086.cn/api",
+                base_url_presets=(
+                    url_preset(
+                        id="china-mobile-moma",
+                        label="MoMA / 移动云",
+                        value="https://ecloud.10086.cn/api",
+                    ),
+                    url_preset(
+                        id="china-mobile-coding",
+                        label="Coding Plan / 移动智算包",
+                        value="https://zhenze-huhehaote.cmecloud.cn/api/coding/v1",
+                    ),
+                ),
+                base_url_editable=True,
+                api_key_hint="填写中国移动 MoMA / 移动云 Token 服务 API Key；如控制台下发专属域名，请覆盖 Base URL。",
+                supports_model_refresh=False,
+                model_list_strategy="manual",
+                description="中国移动 MoMA / 移动云 OpenAI-compatible Token 服务，支持专属域名覆盖。",
+                sort_order=174,
+            ),
+            ProviderSpec(
+                id="china-telecom",
+                name="中国电信",
+                runtime="openai_compatible",
+                default_base_url="https://wishub-x6.ctyun.cn/v1",
+                base_url_presets=(
+                    url_preset(
+                        id="china-telecom-token-service",
+                        label="Token 服务 / 息壤",
+                        value="https://wishub-x6.ctyun.cn/v1",
+                    ),
+                    url_preset(
+                        id="china-telecom-coding-openai",
+                        label="编码套餐 / OpenAI",
+                        value="https://wishub-x6.ctyun.cn/coding/v1",
+                        model_list_strategy="manual",
+                    ),
+                    url_preset(
+                        id="china-telecom-coding-anthropic",
+                        label="编码套餐 / Anthropic",
+                        value="https://wishub-x6.ctyun.cn/coding/v1",
+                        runtime="anthropic_compatible",
+                        model_list_strategy="manual",
+                    ),
+                ),
+                base_url_editable=True,
+                api_key_label="App Key",
+                api_key_hint="填写天翼云 Token 服务 / 息壤 App Key；编码套餐模型请按控制台展示的模型 ID 手动填写。",
+                description="天翼云 Token 服务（原模型推理服务）OpenAI-compatible 端点，支持通用与编码套餐地址预设。",
+                sort_order=176,
+            ),
             ProviderSpec(
                 id="ollama-cloud",
                 name="Ollama Cloud",
@@ -1919,6 +2029,7 @@ class LLMProviderManager(metaclass=Singleton):
                 }
             )
             with self._lock:
+                self._cleanup_auth_sessions_locked()
                 self._pending_sessions[session.session_id] = session
                 self._oauth_state_index[state] = session.session_id
             return {
@@ -1953,6 +2064,7 @@ class LLMProviderManager(metaclass=Singleton):
                 }
             )
             with self._lock:
+                self._cleanup_auth_sessions_locked()
                 self._pending_sessions[session.session_id] = session
             return {
                 "session_id": session.session_id,
@@ -1991,6 +2103,7 @@ class LLMProviderManager(metaclass=Singleton):
                 }
             )
             with self._lock:
+                self._cleanup_auth_sessions_locked()
                 self._pending_sessions[session.session_id] = session
             return {
                 "session_id": session.session_id,
@@ -2007,6 +2120,7 @@ class LLMProviderManager(metaclass=Singleton):
     def get_session_status(self, session_id: str) -> dict[str, Any]:
         """读取临时授权会话状态。"""
         with self._lock:
+            self._cleanup_auth_sessions_locked()
             session = self._pending_sessions.get(session_id)
             if not session:
                 raise LLMProviderAuthError("授权会话不存在或已过期")
@@ -2053,6 +2167,7 @@ class LLMProviderManager(metaclass=Singleton):
         if error:
             message = error_description or error
             with self._lock:
+                self._cleanup_auth_sessions_locked()
                 session_id = self._oauth_state_index.pop(state or "", None)
                 if session_id and session_id in self._pending_sessions:
                     self._mark_session_error(self._pending_sessions[session_id], message)
@@ -2062,6 +2177,7 @@ class LLMProviderManager(metaclass=Singleton):
             return False, "缺少授权码或 state 参数"
 
         with self._lock:
+            self._cleanup_auth_sessions_locked()
             session_id = self._oauth_state_index.pop(state, None)
             session = self._pending_sessions.get(session_id or "")
 
@@ -2104,6 +2220,7 @@ class LLMProviderManager(metaclass=Singleton):
         前端可按 interval_seconds 轮询，直到状态变为 authorized / failed。
         """
         with self._lock:
+            self._cleanup_auth_sessions_locked()
             session = self._pending_sessions.get(session_id)
         if not session:
             raise LLMProviderAuthError("授权会话不存在或已过期")

app/agent/memory/__init__.py

@@ -27,6 +27,8 @@ class MemoryManager:
         初始化记忆管理器
         """
         try:
+            if self.cleanup_task and not self.cleanup_task.done():
+                return
             # 启动内存缓存清理任务（Redis通过TTL自动过期）
             self.cleanup_task = asyncio.create_task(
                 self._cleanup_expired_memories()
@@ -46,6 +48,7 @@ class MemoryManager:
                 await self.cleanup_task
             except asyncio.CancelledError:
                 pass
+            self.cleanup_task = None
 
         logger.info("对话记忆管理器已关闭")
 

app/agent/middleware/skills.py

@@ -157,7 +157,7 @@ def _parse_skill_metadata(  # noqa: C901
             MAX_SKILL_COMPATIBILITY_LENGTH,
             skill_path,
         )
-        compatibility_str = compatibility_str[:MAX_SKILL_COMPATIBILITY_LENGTH]
+        compatibility_str = str(compatibility_str)[:MAX_SKILL_COMPATIBILITY_LENGTH]
 
     # 版本号，默认为 0（表示未设置版本）
     raw_version = frontmatter_data.get("version")

app/agent/middleware/tool_selection.py

@@ -2,11 +2,9 @@
 
 import json
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
-from typing import Annotated, Any, Literal, Union, NotRequired
+from typing import Annotated, Any, NotRequired
 
 from langchain.agents.middleware.types import (
-    AgentMiddleware,
     AgentState,
     ContextT,
     ModelRequest,
@@ -16,78 +14,18 @@ from langchain.agents.middleware.types import (
 from langchain.agents.middleware.types import (
     PrivateStateAttr,  # noqa
 )
+from langchain.agents.middleware.tool_selection import (
+    DEFAULT_SYSTEM_PROMPT,
+    LLMToolSelectorMiddleware,
+)
 from langchain_core.language_models.chat_models import BaseChatModel
-from langchain_core.messages import HumanMessage
 from langchain_core.runnables import RunnableConfig
 from langchain_core.tools import BaseTool
 from langgraph.runtime import Runtime
-from pydantic import Field, TypeAdapter
 from typing_extensions import TypedDict  # noqa
 
 from app.log import logger
 
-DEFAULT_SYSTEM_PROMPT = (
-    "Your goal is to select the most relevant tools for answering the user's query."
-)
-
-
-@dataclass
-class _SelectionRequest:
-    """Prepared inputs for tool selection."""
-
-    available_tools: list[BaseTool]
-    system_message: str
-    last_user_message: HumanMessage
-    model: BaseChatModel
-    valid_tool_names: list[str]
-
-
-def _create_tool_selection_response(tools: list[BaseTool]) -> TypeAdapter[Any]:
-    """Create a structured output schema for tool selection.
-
-    Args:
-        tools: Available tools to include in the schema.
-
-    Returns:
-        `TypeAdapter` for a schema where each tool name is a `Literal` with its
-            description.
-
-    Raises:
-        AssertionError: If `tools` is empty.
-    """
-    if not tools:
-        msg = "Invalid usage: tools must be non-empty"
-        raise AssertionError(msg)
-
-    # Create a Union of Annotated Literal types for each tool name with description
-    # For instance: Union[Annotated[Literal["tool1"], Field(description="...")], ...]
-    literals = [
-        Annotated[Literal[tool.name], Field(description=tool.description)]
-        for tool in tools  # noqa
-    ]
-    selected_tool_type = Union[tuple(literals)]  # type: ignore[valid-type]  # noqa: UP007
-
-    description = "Tools to use. Place the most relevant tools first."
-
-    class ToolSelectionResponse(TypedDict):
-        """Use to select relevant tools."""
-
-        tools: Annotated[list[selected_tool_type], Field(description=description)]  # type: ignore[valid-type]
-
-    return TypeAdapter(ToolSelectionResponse)
-
-
-def _render_tool_list(tools: list[BaseTool]) -> str:
-    """Format tools as markdown list.
-
-    Args:
-        tools: Tools to format.
-
-    Returns:
-        Markdown string with each tool on a new line.
-    """
-    return "\n".join(f"- {tool.name}: {tool.description}" for tool in tools)
-
 
 class ToolSelectionState(AgentState):
     """工具筛选中间件私有状态。"""
@@ -102,9 +40,7 @@ class ToolSelectionStateUpdate(TypedDict):
     selected_tool_names: list[str] | None
 
 
-class ToolSelectorMiddleware(
-    AgentMiddleware[AgentState[ResponseT], ContextT, ResponseT]
-):
+class ToolSelectorMiddleware(LLMToolSelectorMiddleware):
     """
     为 DeepSeek 兼容端点提供更稳妥的工具筛选实现。
 
@@ -129,94 +65,19 @@ class ToolSelectorMiddleware(
 
     def __init__(
             self,
-            model: BaseChatModel,
+            model: BaseChatModel | str | None = None,
             system_prompt: str = DEFAULT_SYSTEM_PROMPT,
             selection_tools: list[Any] | None = None,
             max_tools: int | None = None,
             always_include: list[str] | None = None,
     ) -> None:
-        super().__init__()
-        self.model = model
-        self.system_prompt = system_prompt
-        self.max_tools = max_tools
-        self.always_include = always_include or []
-        self.selection_tools = selection_tools or []
-
-    def _prepare_selection_request(
-            self, request: ModelRequest[ContextT]
-    ) -> _SelectionRequest | None:
-        """Prepare inputs for tool selection.
-
-        Args:
-            request: the model request.
-
-        Returns:
-            `SelectionRequest` with prepared inputs, or `None` if no selection is
-            needed.
-
-        Raises:
-            ValueError: If tools in `always_include` are not found in the request.
-            AssertionError: If no user message is found in the request messages.
-        """
-        # If no tools available, return None
-        if not request.tools or len(request.tools) == 0:
-            return None
-
-        # Filter to only BaseTool instances (exclude provider-specific tool dicts)
-        base_tools = [tool for tool in request.tools if not isinstance(tool, dict)]
-
-        # Validate that always_include tools exist
-        if self.always_include:
-            available_tool_names = {tool.name for tool in base_tools}
-            missing_tools = [
-                name for name in self.always_include if name not in available_tool_names
-            ]
-            if missing_tools:
-                msg = (
-                    f"Tools in always_include not found in request: {missing_tools}. "
-                    f"Available tools: {sorted(available_tool_names)}"
-                )
-                raise ValueError(msg)
-
-        # Separate tools that are always included from those available for selection
-        available_tools = [
-            tool for tool in base_tools if tool.name not in self.always_include
-        ]
-
-        # If no tools available for selection, return None
-        if not available_tools:
-            return None
-
-        system_message = self.system_prompt
-        # If there's a max_tools limit, append instructions to the system prompt
-        if self.max_tools is not None:
-            system_message += (
-                f"\nIMPORTANT: List the tool names in order of relevance, "
-                f"with the most relevant first. "
-                f"If you exceed the maximum number of tools, "
-                f"only the first {self.max_tools} will be used."
-            )
-
-        # Get the last user message from the conversation history
-        last_user_message: HumanMessage
-        for message in reversed(request.messages):
-            if isinstance(message, HumanMessage):
-                last_user_message = message
-                break
-        else:
-            msg = "No user message found in request messages"
-            raise AssertionError(msg)
-
-        model = self.model or request.model
-        valid_tool_names = [tool.name for tool in available_tools]
-
-        return _SelectionRequest(
-            available_tools=available_tools,
-            system_message=system_message,
-            last_user_message=last_user_message,
+        super().__init__(
             model=model,
-            valid_tool_names=valid_tool_names,
+            system_prompt=system_prompt,
+            max_tools=max_tools,
+            always_include=always_include,
         )
+        self.selection_tools = selection_tools or []
 
     def _process_selection_response(
             self,
@@ -225,46 +86,29 @@ class ToolSelectorMiddleware(
             valid_tool_names: list[str],
             request: ModelRequest[ContextT],
     ) -> ModelRequest[ContextT]:
-        """Process the selection response and return filtered `ModelRequest`."""
-        selected_tool_names: list[str] = []
-        invalid_tool_selections = []
-
-        for tool_name in response["tools"]:
-            if tool_name not in valid_tool_names:
-                invalid_tool_selections.append(tool_name)
-                continue
-
-            # Only add if not already selected and within max_tools limit
-            if tool_name not in selected_tool_names and (
-                    self.max_tools is None or len(selected_tool_names) < self.max_tools
-            ):
-                selected_tool_names.append(tool_name)
-
-        if invalid_tool_selections:
-            msg = f"Model selected invalid tools: {invalid_tool_selections}"
-            raise ValueError(msg)
-
-        # Filter tools based on selection and append always-included tools
-        if selected_tool_names:
-            selected_tools: list[BaseTool] = [
-                tool for tool in available_tools if tool.name in selected_tool_names
-            ]
-        else:
-            # 如果模型筛选结果为空，则不对工具进行裁剪，使用所有可用工具
+        """
+        处理工具筛选响应，并保留空结果回退所有工具的 MoviePilot 策略。
+        """
+        if response.get("tools") == []:
             logger.warning("工具筛选结果为空，将恢复使用所有工具。")
-            selected_tools = available_tools
 
-        always_included_tools: list[BaseTool] = [
-            tool
-            for tool in request.tools
-            if not isinstance(tool, dict) and tool.name in self.always_include
-        ]
-        selected_tools.extend(always_included_tools)
+            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)]
 
-        # Also preserve any provider-specific tool dicts from the original request
-        provider_tools = [tool for tool in request.tools if isinstance(tool, dict)]
+            return request.override(
+                tools=[*available_tools, *always_included_tools, *provider_tools]
+            )
 
-        return request.override(tools=[*selected_tools, *provider_tools])
+        return super()._process_selection_response(
+            response,
+            available_tools,
+            valid_tool_names,
+            request,
+        )
 
     @staticmethod
     def _is_deepseek_compatible_model(model: BaseChatModel) -> bool:

app/agent/prompt/System Core Prompt.txt

@@ -56,6 +56,7 @@ Tool Calling Strategy:
 - 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.
 
 Media Management 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.

app/agent/prompt/__init__.py

@@ -1,5 +1,6 @@
 """提示词管理器"""
 
+import shutil
 import socket
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -22,6 +23,31 @@ from app.utils.system import SystemUtils
 
 SYSTEM_TASKS_FILE = "System Tasks.yaml"
 SYSTEM_TASKS_SCHEMA_VERSION = 2
+COMMON_SHELL_COMMANDS = (
+    # 只探测会明显改变 Agent 执行策略的可选能力。基础命令、语言运行时、
+    # 包管理器、服务管理器和数据库客户端默认不做启动探测，减少 which 扫描量。
+    "ssh",
+    "scp",
+    "sftp",
+    "git",
+    "gh",
+    "rg",
+    "fd",
+    "jq",
+    "yq",
+    "curl",
+    "wget",
+    "docker",
+    "docker-compose",
+    "python",
+    "python3",
+    "ffmpeg",
+    "ffprobe",
+    "mediainfo",
+    "rclone",
+    "aria2c",
+    "yt-dlp",
+)
 
 
 class PromptConfigError(ValueError):
@@ -65,6 +91,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
 
     def load_prompt(self, prompt_name: str) -> str:
         """
@@ -252,8 +279,7 @@ class PromptManager:
             sections.append(self._format_numbered_rules("IMPORTANT", rules))
         return "\n\n".join(section for section in sections if section).strip()
 
-    @staticmethod
-    def _get_moviepilot_info() -> str:
+    def _get_moviepilot_info(self) -> str:
         """
         获取MoviePilot系统信息，用于注入到系统提示词中
         """
@@ -303,10 +329,47 @@ class PromptManager:
             f"- 配置文件目录: {config_path}",
             f"- 日志文件目录: {log_path}",
             f"- 系统安装目录: {settings.ROOT_PATH}",
+            f"- 插件安装目录: {settings.ROOT_PATH / 'app' / 'plugins'}",
         ]
 
+        available_commands = self._get_available_shell_commands()
+        if available_commands:
+            info_lines.append("- 可用系统命令（可通过 `execute_command` 调用）:")
+            info_lines.extend(
+                f"  - {command}: {path}" for command, path in available_commands
+            )
+            # `rg` 同时覆盖文件枚举和文本检索，且比通用 shell 查找更适合
+            # Agent 的代码阅读与定位场景；只有在它不可用或不适合时才退回其他工具。
+            if any(command == "rg" for command, _ 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."
+                )
+
         return "\n".join(info_lines)
 
+    def _get_available_shell_commands(self) -> list[tuple[str, str]]:
+        """
+        探测 PATH 中已经安装的常用命令。
+
+        这里只使用 shutil.which 做无副作用查找，不实际执行命令；执行权限、
+        高风险操作确认和输出限制仍由 execute_command 工具负责。探测结果
+        在进程内缓存，避免每次组装提示词都重复扫描 PATH。
+        """
+        if self._available_shell_commands_cache is not None:
+            return self._available_shell_commands_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
+        return available_commands
+
+    def clear_available_shell_commands_cache(self) -> None:
+        """清理可用系统命令缓存，供测试或运行时手动刷新使用。"""
+        self._available_shell_commands_cache = None
+
     @staticmethod
     def _generate_formatting_instructions(caps: ChannelCapabilities) -> str:
         """

app/agent/tools/base.py

@@ -212,8 +212,15 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         # 执行具体工具逻辑
         try:
             result = await self.run(**kwargs)
-            result_len = len(str(result)) if result is not None else 0
-            logger.debug(f"Tool {self.name} executed, raw result length: {result_len}")
+            
+            # 记录工具执行结果摘要日志
+            str_result = serialize_tool_result_for_agent(result)
+            if len(str_result) > 500:
+                summary = str_result[:500] + f"...(已截断，总长度: {len(str_result)})"
+            else:
+                summary = str_result
+            logger.info(f"Agent工具 {self.name} 执行完成，结果摘要: {summary}")
+            
         except Exception as e:
             error_message = f"工具执行异常 ({type(e).__name__}): {str(e)}"
             logger.error(f"Tool {self.name} execution failed: {e}", exc_info=True)
@@ -236,7 +243,8 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         Returns:
             str: 友好的提示消息，如果返回 None 或空字符串则使用 explanation
         """
-        return None
+        explanation = kwargs.get("explanation")
+        return str(explanation) if explanation else None
 
     @abstractmethod
     async def run(self, **kwargs) -> str:
@@ -278,7 +286,9 @@ class MoviePilotTool(BaseTool, metaclass=ABCMeta):
         """
         设置与当前 Agent 共享的上下文。
         """
-        self._agent_context = agent_context or {}
+        # 空 dict 也是合法共享上下文；不能用 ``or {}``，否则每个工具会拿到
+        # 独立的新 dict，跨工具状态（例如质量门槛拒绝标记）无法传播。
+        self._agent_context = {} if agent_context is None else agent_context
 
     async def _check_permission(self) -> Optional[str]:
         """

app/agent/tools/impl/_plugin_tool_utils.py

@@ -1,5 +1,6 @@
 """插件 Agent 工具共享辅助方法"""
 
+import asyncio
 import json
 import shutil
 from typing import Any, Optional
@@ -93,6 +94,9 @@ def summarize_plugin(plugin: Any) -> dict[str, Any]:
         "plugin_author": getattr(plugin, "plugin_author", None),
         "installed": bool(getattr(plugin, "installed", False)),
         "has_update": bool(getattr(plugin, "has_update", False)),
+        "system_version_compatible": getattr(plugin, "system_version_compatible", True) is not False,
+        "system_version": getattr(plugin, "system_version", None),
+        "system_version_message": getattr(plugin, "system_version_message", None),
         "state": bool(getattr(plugin, "state", False)),
         "repo_url": repo_url,
         "source": "local_repo" if PluginHelper.is_local_repo_url(repo_url) else "market",
@@ -245,7 +249,7 @@ async def install_plugin_runtime(
             SystemConfigKey.UserInstalledPlugins, install_plugins
         )
 
-    reload_plugin_runtime(plugin_id)
+    await asyncio.to_thread(reload_plugin_runtime, plugin_id)
     return True, message or "插件安装成功", refreshed_only
 
 

app/agent/tools/impl/_system_setting_utils.py

@@ -62,6 +62,10 @@ SYSTEMCONFIG_SETTING_METADATA = {
         "group": "custom_identifiers",
         "label": "自定义识别词",
     },
+    SystemConfigKey.EpisodeFormatRuleTable.value: {
+        "group": "transfer",
+        "label": "集数定位规则词表",
+    },
     SystemConfigKey.CustomReleaseGroups.value: {
         "group": "customization",
         "label": "自定义制作组/字幕组",

app/agent/tools/impl/add_custom_filter_rule.py

@@ -19,10 +19,8 @@ from app.schemas.types import SystemConfigKey
 class AddCustomFilterRuleInput(BaseModel):
     """新增自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/add_download.py

@@ -22,7 +22,7 @@ from app.utils.crypto import HashUtils
 
 class AddDownloadInput(BaseModel):
     """添加下载工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     torrent_url: List[str] = Field(
         ...,
         description="One or more torrent_url values. Supports refs from get_search_results (`hash:id`) and magnet links."

app/agent/tools/impl/add_rule_group.py

@@ -23,10 +23,8 @@ from app.schemas.types import SystemConfigKey
 class AddRuleGroupInput(BaseModel):
     """新增过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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(
         ...,

app/agent/tools/impl/add_subscribe.py

@@ -14,10 +14,8 @@ from app.schemas.types import MediaType, MessageChannel
 class AddSubscribeInput(BaseModel):
     """添加订阅工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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')",

app/agent/tools/impl/ask_user_choice.py

@@ -26,9 +26,11 @@ class UserChoiceOptionInput(BaseModel):
 
     @model_validator(mode="after")
     def validate_option(self):
-        if not self.label.strip():
+        label = str(self.label)
+        value = str(self.value)
+        if not label.strip():
             raise ValueError("label 不能为空")
-        if not self.value.strip():
+        if not value.strip():
             raise ValueError("value 不能为空")
         return self
 
@@ -36,10 +38,8 @@ class UserChoiceOptionInput(BaseModel):
 class AskUserChoiceInput(BaseModel):
     """按钮选择工具输入。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why the agent needs the user to choose from buttons",
-    )
+    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,7 +55,8 @@ class AskUserChoiceInput(BaseModel):
 
     @model_validator(mode="after")
     def validate_payload(self):
-        if not self.message.strip():
+        message = str(self.message)
+        if not message.strip():
             raise ValueError("message 不能为空")
         if not self.options:
             raise ValueError("options 至少需要提供一个")
@@ -63,8 +64,11 @@ class AskUserChoiceInput(BaseModel):
 
 
 class AskUserChoiceTool(MoviePilotTool):
+    """发送按钮选择并让当前 Agent 轮次等待用户回调消息。"""
+
     name: str = "ask_user_choice"
     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."
@@ -86,6 +90,15 @@ class AskUserChoiceTool(MoviePilotTool):
             return text[:max_length]
         return text[: max_length - 3] + "..."
 
+    def _blocked_by_feedback_quality_gate(self) -> bool:
+        """反馈 Issue 质量门槛拒绝后，禁止继续发按钮引导改写。
+
+        这是对 ``feedback-issue`` skill 的历史兜底：如果同一轮上下文已经
+        标记反馈内容被质量门槛拒绝，就不能再用按钮诱导用户把测试 / 占位
+        内容改写成“真实问题”。
+        """
+        return bool(self._agent_context.get("feedback_issue_rejected_quality"))
+
     async def run(
         self,
         message: str,
@@ -93,6 +106,17 @@ class AskUserChoiceTool(MoviePilotTool):
         title: Optional[str] = None,
         **kwargs,
     ) -> str:
+        if self._blocked_by_feedback_quality_gate():
+            logger.warning(
+                "ask_user_choice blocked after feedback issue rejected_quality: "
+                "session_id=%s",
+                self._session_id,
+            )
+            return (
+                "反馈 Issue 已被质量门槛拒绝，不能继续发送按钮引导用户改写或重新提交。"
+                "请直接结束本次反馈流程。"
+            )
+
         if not self._channel or not self._source:
             return "当前不在可回传消息的会话中，无法发起按钮选择"
 

app/agent/tools/impl/browse_webpage.py

@@ -38,10 +38,8 @@ class BrowserAction(str, Enum):
 class BrowseWebpageInput(BaseModel):
     """浏览器操作工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this browser action is being performed",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this browser action is being performed",)
     action: str = Field(
         ...,
         description=(
@@ -198,68 +196,62 @@ class BrowseWebpageTool(MoviePilotTool):
         cookies: Optional[str],
         user_agent: Optional[str],
     ) -> str:
-        """在同步上下文中执行 Playwright 浏览器操作"""
-        from playwright.sync_api import sync_playwright
+        """在同步上下文中执行 CloakBrowser 浏览器操作"""
+        from cloakbrowser import launch_context
 
         try:
-            with sync_playwright() as playwright:
-                browser = None
-                context = None
-                page = None
-                try:
-                    # 启动浏览器
-                    browser_type = settings.PLAYWRIGHT_BROWSER_TYPE or "chromium"
-                    browser = playwright[browser_type].launch(headless=True)
-
-                    # 创建上下文
-                    context_kwargs = {}
-                    if user_agent:
-                        context_kwargs["user_agent"] = user_agent
-                    # 设置视口大小
-                    context_kwargs["viewport"] = {
+            context = None
+            page = None
+            try:
+                context_kwargs = {
+                    "viewport": {
                         "width": SCREENSHOT_MAX_WIDTH,
                         "height": SCREENSHOT_MAX_HEIGHT,
                     }
+                }
+                if user_agent:
+                    context_kwargs["user_agent"] = user_agent
 
-                    context = browser.new_context(**context_kwargs)
-                    page = context.new_page()
-                    page.set_default_timeout(timeout * 1000)
+                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})
+                # 设置 cookies
+                if cookies:
+                    page.set_extra_http_headers({"cookie": cookies})
 
-                    # 对于非 goto 操作，如果提供了 url 先导航
-                    if url and browser_action != BrowserAction.GOTO:
-                        page.goto(
-                            url, wait_until="domcontentloaded", timeout=timeout * 1000
-                        )
-                        page.wait_for_load_state("networkidle", timeout=timeout * 1000)
+                # 对于非 goto 操作，如果提供了 url 先导航
+                if url and browser_action != BrowserAction.GOTO:
+                    page.goto(url, wait_until="domcontentloaded", timeout=timeout * 1000)
+                    page.wait_for_load_state("networkidle", timeout=timeout * 1000)
 
-                    # 执行具体操作
-                    result = self._do_action(
-                        page,
-                        browser_action,
-                        url,
-                        selector,
-                        value,
-                        script,
-                        content_type,
-                        timeout,
-                    )
-                    return result
+                # 执行具体操作
+                result = self._do_action(
+                    page,
+                    browser_action,
+                    url,
+                    selector,
+                    value,
+                    script,
+                    content_type,
+                    timeout,
+                )
+                return result
 
-                finally:
-                    if page:
-                        page.close()
-                    if context:
-                        context.close()
-                    if browser:
-                        browser.close()
+            finally:
+                if page:
+                    page.close()
+                if context:
+                    context.close()
 
         except Exception as e:
-            logger.error(f"Playwright 执行失败: {e}", exc_info=True)
-            return f"Playwright 执行失败: {str(e)}"
+            logger.error(f"CloakBrowser 执行失败: {e}", exc_info=True)
+            return f"CloakBrowser 执行失败: {str(e)}"
 
     def _do_action(
         self,

app/agent/tools/impl/delete_custom_filter_rule.py

@@ -19,10 +19,8 @@ from app.schemas.types import SystemConfigKey
 class DeleteCustomFilterRuleInput(BaseModel):
     """删除自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.")
 
 

app/agent/tools/impl/delete_download.py

@@ -12,10 +12,8 @@ from app.log import logger
 class DeleteDownloadInput(BaseModel):
     """删除下载任务工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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)"
     )

app/agent/tools/impl/delete_download_history.py

@@ -13,10 +13,8 @@ from app.log import logger
 class DeleteDownloadHistoryInput(BaseModel):
     """删除下载历史记录工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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"
     )

app/agent/tools/impl/delete_rule_group.py

@@ -18,10 +18,8 @@ from app.schemas.types import SystemConfigKey
 class DeleteRuleGroupInput(BaseModel):
     """删除过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.")
 
 

app/agent/tools/impl/delete_subscribe.py

@@ -15,10 +15,8 @@ from app.schemas.types import EventType
 class DeleteSubscribeInput(BaseModel):
     """删除订阅工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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)",

app/agent/tools/impl/delete_transfer_history.py

@@ -12,10 +12,8 @@ from app.log import logger
 class DeleteTransferHistoryInput(BaseModel):
     """删除整理历史记录工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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"
     )

app/agent/tools/impl/execute_command.py

@@ -1,16 +1,25 @@
-"""执行Shell命令工具"""
+"""执行 Shell 命令工具。"""
+
+from __future__ import annotations
 
 import asyncio
+import json
 import os
 import signal
 import subprocess
 from dataclasses import dataclass, field
 from tempfile import NamedTemporaryFile
-from typing import Optional, TextIO, Type
+from typing import Any, Literal, Optional, TextIO, Type
 
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.impl.terminal_session import (
+    TERMINAL_DEFAULT_READ_BYTES,
+    TERMINAL_MAX_READ_BYTES,
+    TERMINAL_WAIT_DEFAULT_MS,
+    terminal_session_manager,
+)
 from app.log import logger
 
 
@@ -20,6 +29,13 @@ MAX_OUTPUT_PREVIEW_BYTES = 10 * 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)
 
@@ -38,11 +54,13 @@ class _CommandOutput:
 
     @staticmethod
     def _clip_text_to_bytes(text: str, byte_limit: int) -> str:
+        """按 UTF-8 字节数截断文本，避免截断后出现非法字符。"""
         if byte_limit <= 0:
             return ""
         return text.encode("utf-8")[:byte_limit].decode("utf-8", errors="ignore")
 
     def _write_chunk(self, stream_name: str, text: str) -> None:
+        """把输出分片按 stdout/stderr 分段写入临时文件。"""
         if not self.temp_file_handle or not text:
             return
 
@@ -56,6 +74,7 @@ class _CommandOutput:
         self.temp_file_handle.write(text)
 
     def _ensure_temp_file(self) -> None:
+        """首次超出预览上限时创建临时文件并补写已缓存预览。"""
         if self.temp_file_handle:
             return
 
@@ -72,6 +91,7 @@ class _CommandOutput:
             self._write_chunk(stream_name, chunk)
 
     def close(self) -> None:
+        """关闭临时文件句柄，确保输出落盘。"""
         if not self.temp_file_handle:
             return
         self.temp_file_handle.flush()
@@ -79,6 +99,7 @@ class _CommandOutput:
         self.temp_file_handle = None
 
     def append(self, stream_name: str, text: str) -> None:
+        """追加一段输出，超出预览上限后只保留完整日志文件。"""
         if not text:
             return
 
@@ -104,47 +125,162 @@ class _CommandOutput:
 
     @property
     def stdout(self) -> str:
+        """返回当前保留的 stdout 预览。"""
         return "".join(
             text for stream_name, text in self.preview_entries if stream_name == "stdout"
         ).strip()
 
     @property
     def stderr(self) -> str:
+        """返回当前保留的 stderr 预览。"""
         return "".join(
             text for stream_name, text in self.preview_entries if stream_name == "stderr"
         ).strip()
 
 
 class ExecuteCommandInput(BaseModel):
-    """执行Shell命令工具的输入参数模型"""
+    """执行 Shell 命令工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ..., description="Clear explanation of why this command is being executed"
+    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=(
+            "Command action. start launches a managed background session and returns "
+            "session_id. read/wait/write/kill operate on that session. run executes "
+            "once and waits until completion or timeout."
+        ),
+    )
+    command: Optional[str] = Field(
+        None,
+        description="Shell command. Required for action=start or action=run.",
+    )
+    session_id: Optional[str] = Field(
+        None,
+        description="Command session id returned by action=start.",
+    )
+    input_text: Optional[str] = Field(
+        None,
+        description="Text to send to stdin for action=write. Use \\u0003 for Ctrl+C.",
+    )
+    signal_name: Optional[str] = Field(
+        "TERM",
+        description="Signal for action=kill, such as TERM, INT, KILL, or 15.",
+    )
+    cwd: Optional[str] = Field(
+        None,
+        description="Working directory for action=start or action=run.",
+    )
+    env: Optional[dict[str, Any]] = Field(
+        None,
+        description="Additional environment variables for action=start.",
+    )
+    use_pty: Optional[bool] = Field(
+        True,
+        description="Use a pseudo terminal for action=start when supported.",
+    )
+    since_seq: Optional[int] = Field(
+        None,
+        description="For action=read/wait, return output chunks after this seq.",
+    )
+    max_bytes: Optional[int] = Field(
+        TERMINAL_DEFAULT_READ_BYTES,
+        description="For action=read/wait, maximum output bytes to return.",
+    )
+    timeout_ms: Optional[int] = Field(
+        TERMINAL_WAIT_DEFAULT_MS,
+        description="For action=wait, maximum segmented wait time in milliseconds.",
     )
-    command: str = Field(..., description="The shell command to execute")
     timeout: Optional[int] = Field(
-        60, description="Max execution time in seconds (default: 60)"
+        60,
+        description="For action=run, max execution time in seconds.",
     )
 
 
 class ExecuteCommandTool(MoviePilotTool):
+    """统一执行和管理 Shell 命令的 Agent 工具。"""
+
     name: str = "execute_command"
     description: str = (
-        "Safely execute shell commands on the server. Useful for system "
-        "maintenance, checking status, or running custom scripts. Includes "
-        "timeout, concurrency, and output preview limits."
+        "Start and manage shell commands on the server. By default action=start "
+        "launches a background session and immediately returns session_id/status/"
+        "last_seq/output_until_seq. Call the same tool with action=read, wait, "
+        "write, or kill to poll output, wait in short segments, send stdin, or "
+        "terminate it. Use action=run only when a one-shot bounded command result "
+        "is preferred."
     )
     args_schema: Type[BaseModel] = ExecuteCommandInput
     require_admin: bool = True
+    result_max_chars = TERMINAL_MAX_READ_BYTES + 4096
 
     def get_tool_message(self, **kwargs) -> Optional[str]:
-        """根据命令生成友好的提示消息"""
-        command = kwargs.get("command", "")
-        return f"执行系统命令: {command}"
+        """根据命令动作生成友好的提示消息。"""
+        action = kwargs.get("action") or "start"
+        command = kwargs.get("command")
+        session_id = kwargs.get("session_id")
+        if action in {"start", "run"}:
+            return f"执行系统命令: {command or ''}"
+        if action == "read":
+            return f"读取命令输出: {session_id or ''}"
+        if action == "wait":
+            return f"等待命令会话: {session_id or ''}"
+        if action == "write":
+            return f"写入命令输入: {session_id or ''}"
+        if action == "kill":
+            return f"终止命令会话: {session_id or ''}"
+        return f"处理命令会话: {session_id or command or ''}"
+
+    @staticmethod
+    def _dump(payload: dict[str, Any]) -> str:
+        """把结构化命令会话结果转换为 Agent 容易解析的 JSON 字符串。"""
+        return json.dumps(payload, ensure_ascii=False, indent=2)
+
+    @staticmethod
+    def _require_session_id(session_id: Optional[str]) -> str:
+        """校验会话型 action 必须传入 session_id。"""
+        if not session_id:
+            raise ValueError("action 需要传入 session_id")
+        return session_id
+
+    @staticmethod
+    def _require_command(command: Optional[str]) -> str:
+        """校验启动型 action 必须传入 command。"""
+        if not command or not command.strip():
+            raise ValueError("action 需要传入 command")
+        return command
+
+    @staticmethod
+    def _validate_command(command: str) -> 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}")
 
     @staticmethod
     def _normalize_timeout(timeout: Optional[int]) -> tuple[int, Optional[str]]:
-        """限制命令最长运行时间，避免 Agent 传入过大的 timeout。"""
+        """限制一次性执行命令的最长运行时间。"""
         try:
             normalized = int(timeout or DEFAULT_TIMEOUT_SECONDS)
         except (TypeError, ValueError):
@@ -161,7 +297,7 @@ class ExecuteCommandTool(MoviePilotTool):
 
     @staticmethod
     def _subprocess_kwargs() -> dict:
-        """为子进程创建独立进程组，便于超时场景清理整棵子进程。"""
+        """为一次性命令创建独立进程组，便于超时清理整棵子进程。"""
         kwargs = {
             "stdin": subprocess.DEVNULL,
             "stdout": asyncio.subprocess.PIPE,
@@ -179,17 +315,16 @@ class ExecuteCommandTool(MoviePilotTool):
         stream_name: str,
         output: _CommandOutput,
     ) -> None:
-        """按块读取输出，始终只把前 10KB 保留在返回结果中。"""
+        """按块读取一次性命令输出，只把前 10KB 保留在返回结果中。"""
         while True:
             chunk = await stream.read(READ_CHUNK_SIZE)
             if not chunk:
                 break
-
             output.append(stream_name, chunk.decode("utf-8", errors="replace"))
 
     @staticmethod
-    def _terminate_process(process: asyncio.subprocess.Process, sig: int):
-        """向进程组发送终止信号；不支持进程组的平台回退为单进程终止。"""
+    def _terminate_process(process: Any, sig: int) -> None:
+        """向进程组发送终止信号，不支持进程组的平台回退为单进程终止。"""
         try:
             if os.name == "posix":
                 os.killpg(process.pid, sig)
@@ -203,7 +338,7 @@ class ExecuteCommandTool(MoviePilotTool):
     @classmethod
     async def _cleanup_process(
         cls,
-        process: asyncio.subprocess.Process,
+        process: Any,
         wait_task: asyncio.Task,
     ) -> None:
         """先温和终止，失败后强杀，避免超时 shell 遗留子进程。"""
@@ -230,7 +365,7 @@ class ExecuteCommandTool(MoviePilotTool):
 
     @staticmethod
     async def _finish_reader_tasks(reader_tasks: list[asyncio.Task]) -> None:
-        """等待输出读取任务退出，异常只记录不影响工具返回。"""
+        """等待一次性命令输出读取任务退出，异常只记录不影响工具返回。"""
         if not reader_tasks:
             return
         done, pending = await asyncio.wait(reader_tasks, timeout=1)
@@ -244,7 +379,7 @@ class ExecuteCommandTool(MoviePilotTool):
                 logger.debug("命令输出读取任务异常: %s", result)
 
     @staticmethod
-    def _format_result(
+    def _format_run_result(
         *,
         exit_code: Optional[int],
         output: _CommandOutput,
@@ -252,6 +387,7 @@ class ExecuteCommandTool(MoviePilotTool):
         timed_out: bool,
         timeout_note: Optional[str],
     ) -> str:
+        """格式化 action=run 的兼容文本结果。"""
         if timed_out:
             result = f"命令执行超时 (限制: {timeout}秒，已终止进程)"
         else:
@@ -260,11 +396,7 @@ class ExecuteCommandTool(MoviePilotTool):
         if timeout_note:
             result += f"\n\n提示:\n{timeout_note}"
         if output.temp_file_path:
-            file_note = (
-                "截至命令终止前的完整输出"
-                if timed_out
-                else "完整输出"
-            )
+            file_note = "截至命令终止前的完整输出" if timed_out else "完整输出"
             result += (
                 "\n\n提示:\n"
                 f"命令输出超过 10KB，仅返回前 {MAX_OUTPUT_PREVIEW_BYTES} 字节内容。\n"
@@ -281,65 +413,129 @@ class ExecuteCommandTool(MoviePilotTool):
             result += "\n\n(无输出内容)"
         return result
 
-    async def run(self, command: str, timeout: Optional[int] = 60, **kwargs) -> str:
-        logger.info(
-            f"执行工具: {self.name}, 参数: command={command}, timeout={timeout}"
-        )
-
-        # 简单安全过滤
-        forbidden_keywords = [
-            "rm -rf /",
-            ":(){ :|:& };:",
-            "dd if=/dev/zero",
-            "mkfs",
-            "reboot",
-            "shutdown",
-        ]
-        for keyword in forbidden_keywords:
-            if keyword in command:
-                return f"错误：命令包含禁止使用的关键字 '{keyword}'"
-
+    async def _run_once(
+        self,
+        *,
+        command: str,
+        timeout: Optional[int],
+        cwd: Optional[str] = None,
+    ) -> str:
+        """按旧模式一次性执行命令，等待完成或超时后返回文本结果。"""
+        self._validate_command(command)
         normalized_timeout, timeout_note = self._normalize_timeout(timeout)
 
+        async with _command_semaphore:
+            process = await asyncio.create_subprocess_shell(
+                command,
+                cwd=cwd,
+                **self._subprocess_kwargs(),
+            )
+            output = _CommandOutput(preview_limit_bytes=MAX_OUTPUT_PREVIEW_BYTES)
+            wait_task = asyncio.create_task(process.wait())
+            reader_tasks = [
+                asyncio.create_task(self._read_stream(process.stdout, "stdout", output)),
+                asyncio.create_task(self._read_stream(process.stderr, "stderr", output)),
+            ]
+
+            timed_out = False
+            try:
+                await asyncio.wait_for(
+                    asyncio.shield(wait_task), timeout=normalized_timeout
+                )
+            except asyncio.TimeoutError:
+                timed_out = True
+                await self._cleanup_process(process, wait_task)
+
+            try:
+                await self._finish_reader_tasks(reader_tasks)
+            finally:
+                output.close()
+
+        return self._format_run_result(
+            exit_code=process.returncode,
+            output=output,
+            timeout=normalized_timeout,
+            timed_out=timed_out,
+            timeout_note=timeout_note,
+        )
+
+    async def run(
+        self,
+        action: Optional[str] = "start",
+        command: Optional[str] = None,
+        session_id: Optional[str] = None,
+        input_text: Optional[str] = None,
+        signal_name: Optional[str] = "TERM",
+        cwd: Optional[str] = None,
+        env: Optional[dict[str, Any]] = None,
+        use_pty: Optional[bool] = True,
+        since_seq: Optional[int] = None,
+        max_bytes: Optional[int] = TERMINAL_DEFAULT_READ_BYTES,
+        timeout_ms: Optional[int] = TERMINAL_WAIT_DEFAULT_MS,
+        timeout: Optional[int] = 60,
+        **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,
+        )
+
         try:
-            async with _command_semaphore:
-                # 命令输出可能非常大，必须边读边落盘，不能使用 communicate() 一次性收集。
-                process = await asyncio.create_subprocess_shell(
-                    command, **self._subprocess_kwargs()
+            if normalized_action == "start":
+                start_command = self._require_command(command)
+                self._validate_command(start_command)
+                payload = await terminal_session_manager.start(
+                    command=start_command,
+                    cwd=cwd,
+                    env=env,
+                    use_pty=use_pty,
                 )
-                output = _CommandOutput(preview_limit_bytes=MAX_OUTPUT_PREVIEW_BYTES)
-                wait_task = asyncio.create_task(process.wait())
-                reader_tasks = [
-                    asyncio.create_task(
-                        self._read_stream(process.stdout, "stdout", output)
-                    ),
-                    asyncio.create_task(
-                        self._read_stream(process.stderr, "stderr", output)
-                    ),
-                ]
+                return self._dump(payload)
 
-                timed_out = False
-                try:
-                    await asyncio.wait_for(
-                        asyncio.shield(wait_task), timeout=normalized_timeout
-                    )
-                except asyncio.TimeoutError:
-                    timed_out = True
-                    await self._cleanup_process(process, wait_task)
+            if normalized_action == "read":
+                payload = await terminal_session_manager.read(
+                    session_id=self._require_session_id(session_id),
+                    since_seq=since_seq,
+                    max_bytes=max_bytes,
+                )
+                return self._dump(payload)
 
-                try:
-                    await self._finish_reader_tasks(reader_tasks)
-                finally:
-                    output.close()
+            if normalized_action == "wait":
+                payload = await terminal_session_manager.wait(
+                    session_id=self._require_session_id(session_id),
+                    timeout_ms=timeout_ms,
+                    since_seq=since_seq,
+                    max_bytes=max_bytes,
+                )
+                return self._dump(payload)
 
-                return self._format_result(
-                    exit_code=process.returncode,
-                    output=output,
-                    timeout=normalized_timeout,
-                    timed_out=timed_out,
-                    timeout_note=timeout_note,
+            if normalized_action == "write":
+                payload = await terminal_session_manager.write(
+                    session_id=self._require_session_id(session_id),
+                    input_text=input_text or "",
+                )
+                return self._dump(payload)
+
+            if normalized_action == "kill":
+                payload = await terminal_session_manager.kill(
+                    session_id=self._require_session_id(session_id),
+                    sig=signal_name,
+                )
+                return self._dump(payload)
+
+            if normalized_action == "run":
+                return await self._run_once(
+                    command=self._require_command(command),
+                    timeout=timeout,
+                    cwd=cwd,
                 )
 
-        except Exception as e:
-            logger.error(f"执行命令失败: {e}", exc_info=True)
-            return f"执行命令时发生错误: {str(e)}"
+            raise ValueError(f"不支持的 action: {action}")
+        except Exception as err:
+            logger.error("执行命令 action 失败: %s", err, exc_info=True)
+            return self._dump({"error": str(err), "status": "error", "action": normalized_action})

app/agent/tools/impl/get_recommendations.py

@@ -14,10 +14,8 @@ from app.schemas.types import MediaType, media_type_to_agent
 class GetRecommendationsInput(BaseModel):
     """获取推荐工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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: "

app/agent/tools/impl/get_search_results.py

@@ -20,10 +20,8 @@ from ._torrent_search_utils import (
 class GetSearchResultsInput(BaseModel):
     """获取搜索结果工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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")

app/agent/tools/impl/install_plugin.py

@@ -18,10 +18,8 @@ from app.log import logger
 class InstallPluginInput(BaseModel):
     """安装插件工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/list_directory.py

@@ -16,7 +16,7 @@ from app.utils.string import StringUtils
 
 class ListDirectoryInput(BaseModel):
     """查询文件系统目录内容工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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')")

app/agent/tools/impl/list_slash_commands.py

@@ -12,10 +12,8 @@ from app.log import logger
 class ListSlashCommandsInput(BaseModel):
     """查询所有可用斜杠命令工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
 
 
 class ListSlashCommandsTool(MoviePilotTool):

app/agent/tools/impl/modify_download.py

@@ -12,10 +12,8 @@ from app.log import logger
 class ModifyDownloadInput(BaseModel):
     """修改下载任务工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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)"
     )

app/agent/tools/impl/query_builtin_filter_rules.py

@@ -17,10 +17,8 @@ from app.log import logger
 class QueryBuiltinFilterRulesInput(BaseModel):
     """查询内置过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/query_custom_filter_rules.py

@@ -18,10 +18,8 @@ from app.log import logger
 class QueryCustomFilterRulesInput(BaseModel):
     """查询自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/query_custom_identifiers.py

@@ -14,10 +14,8 @@ from app.schemas.types import SystemConfigKey
 class QueryCustomIdentifiersInput(BaseModel):
     """查询自定义识别词工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
 
 
 class QueryCustomIdentifiersTool(MoviePilotTool):

app/agent/tools/impl/query_directory_settings.py

@@ -12,7 +12,7 @@ from app.log import logger
 
 class QueryDirectorySettingsInput(BaseModel):
     """查询系统目录设置工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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",

app/agent/tools/impl/query_download_tasks.py

@@ -15,7 +15,7 @@ from app.schemas.types import TorrentStatus, media_type_to_agent
 
 class QueryDownloadTasksInput(BaseModel):
     """查询下载工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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",

app/agent/tools/impl/query_downloaders.py

@@ -13,7 +13,7 @@ from app.schemas.types import SystemConfigKey
 
 class QueryDownloadersInput(BaseModel):
     """查询下载器工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
 
 
 class QueryDownloadersTool(MoviePilotTool):

app/agent/tools/impl/query_episode_schedule.py

@@ -12,7 +12,7 @@ from app.log import logger
 
 class QueryEpisodeScheduleInput(BaseModel):
     """查询剧集上映时间工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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)")

app/agent/tools/impl/query_installed_plugins.py

@@ -20,10 +20,8 @@ from app.log import logger
 class QueryInstalledPluginsInput(BaseModel):
     """查询已安装插件工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/query_library_exists.py

@@ -76,7 +76,7 @@ def _build_tv_server_result(existing_seasons: OrderedDict, total_seasons: Ordere
 
 class QueryLibraryExistsInput(BaseModel):
     """查询媒体库工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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.")
     media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")

app/agent/tools/impl/query_library_latest.py

@@ -17,10 +17,8 @@ PAGE_SIZE = 20
 class QueryLibraryLatestInput(BaseModel):
     """查询媒体服务器最近入库影片工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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)",

app/agent/tools/impl/query_market_plugins.py

@@ -20,10 +20,8 @@ from app.log import logger
 class QueryMarketPluginsInput(BaseModel):
     """查询插件市场工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/query_media_detail.py

@@ -17,7 +17,7 @@ SEASON_PREVIEW_LIMIT = 100
 
 class QueryMediaDetailInput(BaseModel):
     """查询媒体详情工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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)")
     media_type: str = Field(..., description="Allowed values: movie, tv")

app/agent/tools/impl/query_personas.py

@@ -13,10 +13,8 @@ from app.log import logger
 class QueryPersonasInput(BaseModel):
     """查询人格工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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=(

app/agent/tools/impl/query_plugin_capabilities.py

@@ -13,10 +13,8 @@ from app.log import logger
 class QueryPluginCapabilitiesInput(BaseModel):
     """查询插件能力工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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. "

app/agent/tools/impl/query_plugin_config.py

@@ -14,10 +14,8 @@ from app.log import logger
 class QueryPluginConfigInput(BaseModel):
     """查询插件配置工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/query_plugin_data.py

@@ -18,10 +18,8 @@ from app.log import logger
 class QueryPluginDataInput(BaseModel):
     """查询插件数据工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/query_popular_subscribes.py

@@ -17,7 +17,7 @@ MAX_PAGE_SIZE = 50
 
 class QueryPopularSubscribesInput(BaseModel):
     """查询热门订阅工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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)")

app/agent/tools/impl/query_rule_groups.py

@@ -18,10 +18,8 @@ from app.log import logger
 class QueryRuleGroupsInput(BaseModel):
     """查询规则组工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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.",

app/agent/tools/impl/query_schedulers.py

@@ -11,7 +11,7 @@ from app.log import logger
 
 class QuerySchedulersInput(BaseModel):
     """查询定时服务工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
 
 
 class QuerySchedulersTool(MoviePilotTool):

app/agent/tools/impl/query_site_userdata.py

@@ -23,10 +23,8 @@ def _preview_list(value, limit: int = SITE_USERDATA_DETAIL_PREVIEW_LIMIT) -> tup
 class QuerySiteUserdataInput(BaseModel):
     """查询站点用户数据工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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)",

app/agent/tools/impl/query_sites.py

@@ -13,10 +13,8 @@ from app.log import logger
 class QuerySitesInput(BaseModel):
     """查询站点工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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",

app/agent/tools/impl/query_subscribe_history.py

@@ -17,10 +17,8 @@ PAGE_SIZE = 20
 class QuerySubscribeHistoryInput(BaseModel):
     """查询订阅历史工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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"
     )

app/agent/tools/impl/query_subscribe_shares.py

@@ -14,7 +14,7 @@ MAX_PAGE_SIZE = 50
 
 class QuerySubscribeSharesInput(BaseModel):
     """查询订阅分享工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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)")

app/agent/tools/impl/query_subscribes.py

@@ -47,10 +47,8 @@ QUERY_SUBSCRIBE_OUTPUT_FIELDS = [
 class QuerySubscribesInput(BaseModel):
     """查询订阅工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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 subscriptions by status: 'R' for enabled subscriptions, 'S' for paused ones, 'all' for all subscriptions",

app/agent/tools/impl/query_system_settings.py

@@ -19,10 +19,8 @@ from app.log import logger
 class QuerySystemSettingsInput(BaseModel):
     """查询系统设置工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     setting_key: Optional[str] = Field(
         None,
         description=(

app/agent/tools/impl/query_transfer_history.py

@@ -3,7 +3,6 @@
 import json
 from typing import Optional, Type
 
-import jieba
 from pydantic import BaseModel, Field
 
 from app.agent.tools.base import MoviePilotTool
@@ -11,11 +10,12 @@ from app.db import AsyncSessionFactory
 from app.db.models.transferhistory import TransferHistory
 from app.log import logger
 from app.schemas.types import media_type_to_agent
+from app.utils.jieba import cut as jieba_cut
 
 
 class QueryTransferHistoryInput(BaseModel):
     """查询整理历史记录工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     title: Optional[str] = Field(None, description="Search by title (optional, supports partial match)")
     status: Optional[str] = Field("all",
                                   description="Filter by status: 'success' for successful transfers, 'failed' for failed transfers, 'all' for all records (default: 'all')")
@@ -69,8 +69,8 @@ class QueryTransferHistoryTool(MoviePilotTool):
             async with AsyncSessionFactory() as db:
                 # 处理标题搜索
                 if title:
-                    # 使用 jieba 分词处理标题
-                    words = jieba.cut(title, HMM=False)
+                    # 使用统一分词封装处理标题，便于替换底层实现。
+                    words = jieba_cut(title, HMM=False)
                     title_search = "%".join(words)
                     # 查询记录
                     result = await TransferHistory.async_list_by_title(

app/agent/tools/impl/query_workflows.py

@@ -13,7 +13,7 @@ from app.log import logger
 
 class QueryWorkflowsInput(BaseModel):
     """查询工作流工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     state: Optional[str] = Field("all", description="Filter workflows by state: 'W' for waiting, 'R' for running, 'P' for paused, 'S' for success, 'F' for failed, 'all' for all workflows (default: 'all')")
     name: Optional[str] = Field(None, description="Filter workflows by name (partial match, optional)")
     trigger_type: Optional[str] = Field("all", description="Filter workflows by trigger type: 'timer' for scheduled, 'event' for event-triggered, 'manual' for manual, 'all' for all types (default: 'all')")

app/agent/tools/impl/recognize_media.py

@@ -15,7 +15,7 @@ from app.schemas.types import media_type_to_agent
 
 class RecognizeMediaInput(BaseModel):
     """识别媒体信息工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     title: Optional[str] = Field(None, description="The title of the torrent/media to recognize (required for torrent recognition)")
     subtitle: Optional[str] = Field(None, description="The subtitle or description of the torrent (optional, helps improve recognition accuracy)")
     path: Optional[str] = Field(None, description="The file path to recognize (required for file recognition, mutually exclusive with title)")

app/agent/tools/impl/reload_plugin.py

@@ -16,10 +16,8 @@ from app.log import logger
 class ReloadPluginInput(BaseModel):
     """重载插件工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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 reload so the latest saved config takes effect.",

app/agent/tools/impl/run_scheduler.py

@@ -11,10 +11,8 @@ from app.log import logger
 class RunSchedulerInput(BaseModel):
     """运行定时服务工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     job_id: str = Field(
         ...,
         description="The ID of the scheduled job to run (can be obtained from query_schedulers tool)",

app/agent/tools/impl/run_slash_command.py

@@ -14,10 +14,8 @@ from app.schemas.types import EventType, MessageChannel
 class RunSlashCommandInput(BaseModel):
     """运行斜杠命令工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     command: str = Field(
         ...,
         description="The slash command to execute, e.g. '/cookiecloud'. "

app/agent/tools/impl/run_workflow.py

@@ -14,10 +14,8 @@ from app.log import logger
 class RunWorkflowInput(BaseModel):
     """执行工作流工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     workflow_id: int = Field(
         ..., description="Workflow ID (can be obtained from query_workflows tool)"
     )

app/agent/tools/impl/scrape_metadata.py

@@ -15,10 +15,8 @@ from app.schemas import FileItem
 class ScrapeMetadataInput(BaseModel):
     """刮削媒体元数据工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     path: str = Field(
         ...,
         description="Path to the file or directory to scrape metadata for (e.g., '/path/to/file.mkv' or '/path/to/directory')",

app/agent/tools/impl/search_media.py

@@ -13,7 +13,7 @@ from app.schemas.types import MediaType, media_type_to_agent
 
 class SearchMediaInput(BaseModel):
     """搜索媒体工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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 search for (e.g., 'The Matrix', 'Breaking Bad')")
     year: Optional[str] = Field(None, description="Release year of the media (optional, helps narrow down results)")
     media_type: Optional[str] = Field(None,

app/agent/tools/impl/search_person.py

@@ -12,7 +12,7 @@ from app.log import logger
 
 class SearchPersonInput(BaseModel):
     """搜索人物工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     name: str = Field(..., description="The name of the person to search for (e.g., 'Tom Hanks', '周杰伦')")
 
 

app/agent/tools/impl/search_person_credits.py

@@ -14,7 +14,7 @@ from app.log import logger
 
 class SearchPersonCreditsInput(BaseModel):
     """搜索演员参演作品工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     person_id: int = Field(..., description="The ID of the person/actor to search for credits (e.g., 31 for Tom Hanks in TMDB)")
     source: str = Field(..., description="The data source: 'tmdb' for TheMovieDB, 'douban' for Douban, 'bangumi' for Bangumi")
     page: Optional[int] = Field(1, description="Page number for pagination (default: 1)")

app/agent/tools/impl/search_subscribe.py

@@ -14,7 +14,7 @@ from app.schemas.types import media_type_to_agent
 
 class SearchSubscribeInput(BaseModel):
     """搜索订阅缺失剧集工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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 search for missing episodes (can be obtained from query_subscribes tool)")
     manual: Optional[bool] = Field(False, description="Whether this is a manual search (default: False)")
     filter_groups: Optional[List[str]] = Field(None,

app/agent/tools/impl/search_torrents.py

@@ -19,7 +19,7 @@ from ._torrent_search_utils import (
 
 class SearchTorrentsInput(BaseModel):
     """搜索种子工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    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.")
     media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")

app/agent/tools/impl/search_web.py

@@ -19,10 +19,8 @@ SEARCH_TIMEOUT = 20
 class SearchWebInput(BaseModel):
     """搜索网络内容工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     query: str = Field(
         ..., description="The search query string to search for on the web"
     )

app/agent/tools/impl/send_local_file.py

@@ -15,10 +15,8 @@ from app.schemas.types import MessageChannel
 class SendLocalFileInput(BaseModel):
     """发送本地附件工具输入。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why sending this local file helps the user",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why sending this local file helps the user",)
     file_path: str = Field(
         ...,
         description="Absolute path to the local image or file to send to the user",

app/agent/tools/impl/send_message.py

@@ -11,10 +11,8 @@ from app.log import logger
 class SendMessageInput(BaseModel):
     """发送消息工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     message: Optional[str] = Field(
         None,
         description="The message content to send to the user (should be clear and informative)",

app/agent/tools/impl/send_voice_message.py

@@ -15,10 +15,8 @@ from app.schemas import Notification, NotificationType
 class SendVoiceMessageInput(BaseModel):
     """发送语音消息工具输入。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why a voice reply is the best fit in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why a voice reply is the best fit in the current context",)
     message: str = Field(
         ...,
         description="The spoken content to send back to the user",

app/agent/tools/impl/switch_persona.py

@@ -1,7 +1,7 @@
 """切换当前激活人格工具。"""
 
 import json
-from typing import Type
+from typing import Type, Optional
 
 from pydantic import BaseModel, Field
 
@@ -13,10 +13,8 @@ from app.log import logger
 class SwitchPersonaInput(BaseModel):
     """切换人格工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     persona_id: str = Field(
         ...,
         description=(

app/agent/tools/impl/terminal_session.py

@@ -0,0 +1,628 @@
+"""Agent 终端会话管理器。"""
+
+from __future__ import annotations
+
+import asyncio
+import errno
+import os
+import signal
+import subprocess
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from app.core.config import settings
+from app.log import logger
+
+if os.name == "posix":
+    import fcntl as _fcntl
+    import pty as _pty
+else:
+    _fcntl = None
+    _pty = None
+
+
+TERMINAL_CONCURRENCY_LIMIT = 4
+TERMINAL_RETENTION_SECONDS = 30 * 60
+TERMINAL_MAX_RETAINED_BYTES = 1024 * 1024
+TERMINAL_DEFAULT_READ_BYTES = 10 * 1024
+TERMINAL_MAX_READ_BYTES = 64 * 1024
+TERMINAL_READ_CHUNK_SIZE = 4096
+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
+class _TerminalChunk:
+    """记录终端输出分片，供增量读取时按 seq 过滤。"""
+
+    seq: int
+    stream: str
+    text: str
+    byte_size: int
+    created_at: float
+
+
+@dataclass
+class _TerminalSession:
+    """保存一个后台命令会话的进程、输出和状态。"""
+
+    session_id: str
+    command: str
+    cwd: str
+    pid: int
+    use_pty: bool
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    status: str = "running"
+    exit_code: Optional[int] = None
+    process: Optional[asyncio.subprocess.Process] = None
+    master_fd: Optional[int] = None
+    chunks: list[_TerminalChunk] = field(default_factory=list)
+    next_seq: int = 1
+    retained_from_seq: int = 1
+    retained_bytes: int = 0
+    kill_requested: bool = False
+    error: Optional[str] = None
+    reader_tasks: list[asyncio.Task] = field(default_factory=list)
+    wait_task: Optional[asyncio.Task] = None
+
+    def append_output(self, stream: str, data: bytes) -> None:
+        """追加输出并按容量上限丢弃最旧分片，避免长任务撑爆内存。"""
+        if not data:
+            return
+
+        text = data.decode("utf-8", errors="replace")
+        chunk = _TerminalChunk(
+            seq=self.next_seq,
+            stream=stream,
+            text=text,
+            byte_size=len(data),
+            created_at=time.time(),
+        )
+        self.next_seq += 1
+        self.chunks.append(chunk)
+        self.retained_bytes += chunk.byte_size
+        self.updated_at = chunk.created_at
+        self._trim_output()
+
+    def _trim_output(self) -> None:
+        """移除超出保留上限的旧输出分片。"""
+        while self.retained_bytes > TERMINAL_MAX_RETAINED_BYTES and self.chunks:
+            removed = self.chunks.pop(0)
+            self.retained_bytes -= removed.byte_size
+            self.retained_from_seq = removed.seq + 1
+
+    def mark_finished(self, exit_code: Optional[int]) -> None:
+        """标记进程已经结束，并记录退出码。"""
+        self.exit_code = exit_code
+        self.status = "killed" if self.kill_requested else "exited"
+        self.updated_at = time.time()
+
+    def mark_error(self, message: str) -> None:
+        """标记会话异常，保留错误信息供后续读取。"""
+        self.error = message
+        self.status = "error"
+        self.updated_at = time.time()
+
+    def close_pty(self) -> None:
+        """关闭父进程持有的 PTY master fd。"""
+        if self.master_fd is None:
+            return
+        try:
+            os.close(self.master_fd)
+        except OSError:
+            pass
+        self.master_fd = None
+
+
+class _TerminalSessionManager:
+    """管理 Agent 后台终端会话的生命周期。"""
+
+    def __init__(self) -> None:
+        """初始化会话表和并发保护锁。"""
+        self._sessions: dict[str, _TerminalSession] = {}
+        self._lock = asyncio.Lock()
+
+    @staticmethod
+    def _normalize_bool(value: Any, default: bool = True) -> bool:
+        """兼容 LLM 或 HTTP 传入的 bool/string/int 布尔值。"""
+        if value is None:
+            return default
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.strip().lower() not in {"false", "0", "no", "off"}
+        return bool(value)
+
+    @staticmethod
+    def _normalize_cwd(cwd: Optional[str]) -> str:
+        """解析工作目录，未传入时默认使用 MoviePilot 项目根目录。"""
+        if not cwd:
+            return str(settings.ROOT_PATH)
+        path = Path(cwd).expanduser()
+        if not path.is_absolute():
+            path = (settings.ROOT_PATH / path).resolve()
+        else:
+            path = path.resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"工作目录不存在: {path}")
+        if not path.is_dir():
+            raise NotADirectoryError(f"工作目录不是目录: {path}")
+        return str(path)
+
+    @staticmethod
+    def _build_env(env: Optional[dict[str, Any]]) -> dict[str, str]:
+        """合并环境变量，并把值稳定转换为字符串。"""
+        merged_env = os.environ.copy()
+        if not env:
+            return merged_env
+        for key, value in env.items():
+            if value is None:
+                continue
+            merged_env[str(key)] = str(value)
+        return merged_env
+
+    @staticmethod
+    def _validate_command(command: str) -> None:
+        """拒绝明显危险或空白命令。"""
+        if not command or not command.strip():
+            raise ValueError("命令不能为空")
+        for keyword in TERMINAL_FORBIDDEN_KEYWORDS:
+            if keyword in command:
+                raise ValueError(f"命令包含禁止使用的关键字 '{keyword}'")
+
+    @staticmethod
+    def _set_nonblocking(fd: int) -> None:
+        """将 PTY master fd 设置为非阻塞，避免后台读取任务卡住事件循环。"""
+        if _fcntl is None:
+            raise RuntimeError("当前平台不支持 PTY 非阻塞设置")
+        flags = _fcntl.fcntl(fd, _fcntl.F_GETFL)
+        _fcntl.fcntl(fd, _fcntl.F_SETFL, flags | os.O_NONBLOCK)
+
+    @staticmethod
+    def _pipe_subprocess_kwargs() -> dict[str, Any]:
+        """生成普通管道模式的子进程参数。"""
+        kwargs: dict[str, Any] = {
+            "stdin": asyncio.subprocess.PIPE,
+            "stdout": asyncio.subprocess.PIPE,
+            "stderr": asyncio.subprocess.PIPE,
+        }
+        if os.name == "posix":
+            kwargs["start_new_session"] = True
+        elif os.name == "nt":
+            kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+        return kwargs
+
+    async def start(
+        self,
+        *,
+        command: str,
+        cwd: Optional[str] = None,
+        env: Optional[dict[str, Any]] = None,
+        use_pty: Any = True,
+    ) -> dict[str, Any]:
+        """启动后台命令并立即返回会话 ID。"""
+        self._validate_command(command)
+        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"
+
+        async with self._lock:
+            self._cleanup_finished_sessions_locked()
+            if self._active_session_count_locked() >= TERMINAL_CONCURRENCY_LIMIT:
+                raise RuntimeError(
+                    f"后台终端会话数已达到上限 {TERMINAL_CONCURRENCY_LIMIT}"
+                )
+
+        session = (
+            await self._start_pty_session(command, normalized_cwd, normalized_env)
+            if should_use_pty
+            else await self._start_pipe_session(command, normalized_cwd, normalized_env)
+        )
+
+        async with self._lock:
+            self._sessions[session.session_id] = session
+
+        logger.info(
+            "启动后台终端会话: session_id=%s, pid=%s, use_pty=%s, command=%s",
+            session.session_id,
+            session.pid,
+            session.use_pty,
+            command,
+        )
+        await asyncio.sleep(0)
+        return self._session_payload(session, output="", output_truncated=False)
+
+    async def _start_pty_session(
+        self, command: str, cwd: str, env: dict[str, str]
+    ) -> _TerminalSession:
+        """通过 PTY fork 启动交互式命令会话。"""
+        if _pty is None:
+            raise RuntimeError("当前平台不支持 PTY 会话")
+        pid, master_fd = _pty.fork()
+        if pid == 0:
+            os.chdir(cwd)
+            os.environ.clear()
+            os.environ.update(env)
+            shell = os.environ.get("SHELL") or "/bin/sh"
+            os.execl(shell, shell, "-lc", command)
+
+        self._set_nonblocking(master_fd)
+        session = _TerminalSession(
+            session_id=f"term_{uuid.uuid4().hex[:12]}",
+            command=command,
+            cwd=cwd,
+            pid=pid,
+            use_pty=True,
+            master_fd=master_fd,
+        )
+        session.reader_tasks.append(asyncio.create_task(self._read_pty(session)))
+        session.wait_task = asyncio.create_task(self._wait_pty_process(session))
+        return session
+
+    async def _start_pipe_session(
+        self, command: str, cwd: str, env: dict[str, str]
+    ) -> _TerminalSession:
+        """通过普通 stdin/stdout/stderr 管道启动命令会话。"""
+        process = await asyncio.create_subprocess_shell(
+            command,
+            cwd=cwd,
+            env=env,
+            **self._pipe_subprocess_kwargs(),
+        )
+        session = _TerminalSession(
+            session_id=f"term_{uuid.uuid4().hex[:12]}",
+            command=command,
+            cwd=cwd,
+            pid=process.pid or 0,
+            use_pty=False,
+            process=process,
+        )
+        if process.stdout:
+            session.reader_tasks.append(
+                asyncio.create_task(self._read_pipe(session, process.stdout, "stdout"))
+            )
+        if process.stderr:
+            session.reader_tasks.append(
+                asyncio.create_task(self._read_pipe(session, process.stderr, "stderr"))
+            )
+        session.wait_task = asyncio.create_task(self._wait_pipe_process(session))
+        return session
+
+    async def _read_pty(self, session: _TerminalSession) -> None:
+        """持续从 PTY 读取增量输出。"""
+        while session.master_fd is not None:
+            try:
+                data = os.read(session.master_fd, TERMINAL_READ_CHUNK_SIZE)
+            except BlockingIOError:
+                await asyncio.sleep(TERMINAL_PTY_POLL_INTERVAL)
+                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)
+                break
+
+            if not data:
+                break
+            session.append_output("pty", data)
+
+    async def _read_pipe(
+        self,
+        session: _TerminalSession,
+        stream: asyncio.StreamReader,
+        stream_name: str,
+    ) -> None:
+        """持续从普通管道读取增量输出。"""
+        while True:
+            data = await stream.read(TERMINAL_READ_CHUNK_SIZE)
+            if not data:
+                break
+            session.append_output(stream_name, data)
+
+    async def _wait_pty_process(self, session: _TerminalSession) -> None:
+        """等待 PTY 子进程结束并完成输出读取任务收尾。"""
+        try:
+            _, status = await asyncio.to_thread(os.waitpid, session.pid, 0)
+            exit_code = os.waitstatus_to_exitcode(status)
+            session.mark_finished(exit_code)
+        except ChildProcessError:
+            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)
+        finally:
+            await self._finish_reader_tasks(session)
+            session.close_pty()
+
+    async def _wait_pipe_process(self, session: _TerminalSession) -> None:
+        """等待普通管道子进程结束并完成输出读取任务收尾。"""
+        try:
+            if not session.process:
+                session.mark_error("进程对象不存在")
+                return
+            exit_code = await session.process.wait()
+            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)
+        finally:
+            await self._finish_reader_tasks(session)
+
+    async def _finish_reader_tasks(self, session: _TerminalSession) -> None:
+        """等待输出读取任务退出，超时后取消残留任务。"""
+        if not session.reader_tasks:
+            return
+        done, pending = await asyncio.wait(session.reader_tasks, timeout=1)
+        for task in pending:
+            task.cancel()
+        await asyncio.gather(*done, *pending, return_exceptions=True)
+
+    async def read(
+        self,
+        *,
+        session_id: str,
+        since_seq: Optional[int] = None,
+        max_bytes: Optional[int] = TERMINAL_DEFAULT_READ_BYTES,
+    ) -> dict[str, Any]:
+        """读取会话当前保留的增量输出。"""
+        session = self.get_session(session_id)
+        output, output_truncated, output_until_seq = self._collect_output(
+            session,
+            since_seq=since_seq,
+            max_bytes=max_bytes,
+        )
+        return self._session_payload(
+            session,
+            output=output,
+            output_truncated=output_truncated,
+            output_until_seq=output_until_seq,
+        )
+
+    async def wait(
+        self,
+        *,
+        session_id: str,
+        timeout_ms: Optional[int] = TERMINAL_WAIT_DEFAULT_MS,
+        since_seq: Optional[int] = None,
+        max_bytes: Optional[int] = TERMINAL_DEFAULT_READ_BYTES,
+    ) -> dict[str, Any]:
+        """短暂等待会话结束，并返回等待期间可见的增量输出。"""
+        session = self.get_session(session_id)
+        normalized_timeout = self._normalize_wait_timeout(timeout_ms)
+        if session.wait_task and not session.wait_task.done():
+            try:
+                await asyncio.wait_for(
+                    asyncio.shield(session.wait_task),
+                    timeout=normalized_timeout / 1000,
+                )
+            except asyncio.TimeoutError:
+                pass
+
+        output, output_truncated, output_until_seq = self._collect_output(
+            session,
+            since_seq=since_seq,
+            max_bytes=max_bytes,
+        )
+        payload = self._session_payload(
+            session,
+            output=output,
+            output_truncated=output_truncated,
+            output_until_seq=output_until_seq,
+        )
+        payload["wait_timeout_ms"] = normalized_timeout
+        return payload
+
+    async def write(self, *, session_id: str, input_text: str) -> dict[str, Any]:
+        """向会话 stdin 写入文本，PTY 模式下写入 master fd。"""
+        session = self.get_session(session_id)
+        if session.status != "running":
+            raise RuntimeError(f"会话已结束，当前状态: {session.status}")
+
+        data = (input_text or "").encode("utf-8")
+        if session.use_pty:
+            if session.master_fd is None:
+                raise RuntimeError("PTY 已关闭")
+            await asyncio.to_thread(os.write, session.master_fd, data)
+        else:
+            if not session.process or not session.process.stdin:
+                raise RuntimeError("进程 stdin 不可写")
+            session.process.stdin.write(data)
+            await session.process.stdin.drain()
+
+        session.updated_at = time.time()
+        payload = self._session_payload(session, output="", output_truncated=False)
+        payload["written_bytes"] = len(data)
+        return payload
+
+    async def kill(
+        self,
+        *,
+        session_id: str,
+        sig: Optional[str | int] = "TERM",
+    ) -> dict[str, Any]:
+        """向会话进程组发送信号并等待短暂清理。"""
+        session = self.get_session(session_id)
+        if session.status != "running":
+            return self._session_payload(session, output="", output_truncated=False)
+
+        session.kill_requested = True
+        signal_number = self._resolve_signal(sig)
+        self._send_signal(session, signal_number)
+
+        if session.wait_task and not session.wait_task.done():
+            try:
+                await asyncio.wait_for(
+                    asyncio.shield(session.wait_task),
+                    timeout=TERMINAL_KILL_GRACE_SECONDS,
+                )
+            except asyncio.TimeoutError:
+                force_signal = getattr(signal, "SIGKILL", signal.SIGTERM)
+                self._send_signal(session, force_signal)
+
+        return self._session_payload(session, output="", output_truncated=False)
+
+    def get_session(self, session_id: str) -> _TerminalSession:
+        """按 ID 获取会话，不存在时抛出清晰错误。"""
+        session = self._sessions.get(session_id)
+        if not session:
+            raise KeyError(f"终端会话不存在: {session_id}")
+        return session
+
+    @staticmethod
+    def _normalize_wait_timeout(timeout_ms: Optional[int]) -> int:
+        """限制 wait 单次等待时间，避免工具调用长时间占用模型回合。"""
+        try:
+            normalized = int(timeout_ms or TERMINAL_WAIT_DEFAULT_MS)
+        except (TypeError, ValueError):
+            normalized = TERMINAL_WAIT_DEFAULT_MS
+        if normalized < 0:
+            return 0
+        return min(normalized, TERMINAL_WAIT_MAX_MS)
+
+    @staticmethod
+    def _normalize_read_limit(max_bytes: Optional[int]) -> int:
+        """限制单次读取返回的输出大小。"""
+        try:
+            normalized = int(max_bytes or TERMINAL_DEFAULT_READ_BYTES)
+        except (TypeError, ValueError):
+            normalized = TERMINAL_DEFAULT_READ_BYTES
+        if normalized <= 0:
+            return TERMINAL_DEFAULT_READ_BYTES
+        return min(normalized, TERMINAL_MAX_READ_BYTES)
+
+    def _collect_output(
+        self,
+        session: _TerminalSession,
+        *,
+        since_seq: Optional[int],
+        max_bytes: Optional[int],
+    ) -> tuple[str, bool, int]:
+        """按 seq 和大小限制收集输出文本。"""
+        read_limit = self._normalize_read_limit(max_bytes)
+        selected_chunks = [
+            chunk
+            for chunk in session.chunks
+            if since_seq is None or chunk.seq > since_seq
+        ]
+        output_parts: list[str] = []
+        output_bytes = 0
+        output_truncated = False
+        last_stream: Optional[str] = None
+        output_until_seq = since_seq or session.retained_from_seq - 1
+
+        for chunk in selected_chunks:
+            prefix = self._stream_prefix(chunk.stream, last_stream, session.use_pty)
+            text = f"{prefix}{chunk.text}" if prefix else chunk.text
+            encoded = text.encode("utf-8")
+            remaining = read_limit - output_bytes
+            if len(encoded) > remaining:
+                if remaining > 0:
+                    output_parts.append(
+                        encoded[:remaining].decode("utf-8", errors="ignore")
+                    )
+                output_truncated = True
+                break
+            output_parts.append(text)
+            output_bytes += len(encoded)
+            last_stream = chunk.stream
+            output_until_seq = chunk.seq
+
+        if since_seq is not None and since_seq < session.retained_from_seq - 1:
+            output_truncated = True
+        if not output_truncated:
+            output_until_seq = session.next_seq - 1
+        return "".join(output_parts), output_truncated, output_until_seq
+
+    @staticmethod
+    def _stream_prefix(stream: str, last_stream: Optional[str], use_pty: bool) -> str:
+        """为普通管道输出增加 stdout/stderr 分段标识。"""
+        if use_pty or stream == last_stream:
+            return ""
+        title = "标准输出" if stream == "stdout" else "错误输出"
+        return f"\n[{title}]\n"
+
+    @staticmethod
+    def _resolve_signal(sig: Optional[str | int]) -> int:
+        """解析字符串或数字形式的信号名。"""
+        if isinstance(sig, int):
+            return sig
+        signal_name = str(sig or "TERM").strip().upper()
+        if signal_name.isdigit():
+            return int(signal_name)
+        if not signal_name.startswith("SIG"):
+            signal_name = f"SIG{signal_name}"
+        return int(getattr(signal, signal_name, signal.SIGTERM))
+
+    @staticmethod
+    def _send_signal(session: _TerminalSession, sig: int) -> None:
+        """优先向进程组发信号，失败时回退到单进程。"""
+        try:
+            if os.name == "posix":
+                os.killpg(session.pid, sig)
+            elif session.process:
+                if sig == getattr(signal, "SIGKILL", None):
+                    session.process.kill()
+                else:
+                    session.process.terminate()
+        except ProcessLookupError:
+            pass
+
+    def _active_session_count_locked(self) -> int:
+        """统计仍在运行的会话数量。"""
+        return sum(1 for session in self._sessions.values() if session.status == "running")
+
+    def _cleanup_finished_sessions_locked(self) -> None:
+        """清理已经结束且超过保留时间的会话。"""
+        now = time.time()
+        expired_ids = [
+            session_id
+            for session_id, session in self._sessions.items()
+            if session.status != "running"
+            and now - session.updated_at > TERMINAL_RETENTION_SECONDS
+        ]
+        for session_id in expired_ids:
+            session = self._sessions.pop(session_id)
+            session.close_pty()
+
+    @staticmethod
+    def _session_payload(
+        session: _TerminalSession,
+        *,
+        output: str,
+        output_truncated: bool,
+        output_until_seq: Optional[int] = None,
+    ) -> dict[str, Any]:
+        """生成工具返回的结构化会话状态。"""
+        return {
+            "session_id": session.session_id,
+            "command": session.command,
+            "cwd": session.cwd,
+            "pid": session.pid,
+            "status": session.status,
+            "exit_code": session.exit_code,
+            "use_pty": session.use_pty,
+            "last_seq": session.next_seq - 1,
+            "output_until_seq": (
+                session.next_seq - 1 if output_until_seq is None else output_until_seq
+            ),
+            "retained_from_seq": session.retained_from_seq,
+            "output_truncated": output_truncated,
+            "output": output,
+            "error": session.error,
+        }
+
+
+terminal_session_manager = _TerminalSessionManager()

app/agent/tools/impl/test_site.py

@@ -12,7 +12,7 @@ from app.log import logger
 
 class TestSiteInput(BaseModel):
     """测试站点连通性工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     site_identifier: int = Field(..., description="Site ID to test (can be obtained from query_sites tool)")
 
 

app/agent/tools/impl/transfer_file.py

@@ -13,10 +13,8 @@ from app.schemas import FileItem, MediaType
 class TransferFileInput(BaseModel):
     """整理文件或目录工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     file_path: str = Field(
         ...,
         description="Path to the file or directory to transfer (e.g., '/path/to/file.mkv' or '/path/to/directory')",

app/agent/tools/impl/uninstall_plugin.py

@@ -17,10 +17,8 @@ from app.log import logger
 class UninstallPluginInput(BaseModel):
     """卸载插件工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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 uninstall. Use query_installed_plugins first to find the correct plugin_id.",

app/agent/tools/impl/update_custom_filter_rule.py

@@ -22,10 +22,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateCustomFilterRuleInput(BaseModel):
     """更新自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     current_rule_id: str = Field(
         ..., description="Existing custom rule ID to update."
     )

app/agent/tools/impl/update_custom_identifiers.py

@@ -14,10 +14,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateCustomIdentifiersInput(BaseModel):
     """更新自定义识别词工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     identifiers: List[str] = Field(
         ...,
         description=(
@@ -50,7 +48,8 @@ class UpdateCustomIdentifiersTool(MoviePilotTool):
         "3) Episode offset: '前定位词 <> 后定位词 >> EP±N'; "
         "4) Combined: '被替换词 => 替换词 && 前定位词 <> 后定位词 >> EP±N'; "
         "Lines starting with '#' are comments. "
-        "The replacement target supports: {[tmdbid=xxx;type=movie/tv;s=xxx;e=xxx]} for direct TMDB ID matching."
+        "The replacement target supports: {[tmdbid=xxx;type=movie/tv;g=xxx;s=xxx;e=xxx]} "
+        "for direct TMDB ID matching; g is an optional TMDB episode group ID for TV recognition."
     )
     require_admin: bool = True
     args_schema: Type[BaseModel] = UpdateCustomIdentifiersInput

app/agent/tools/impl/update_persona_definition.py

@@ -13,10 +13,8 @@ from app.log import logger
 class UpdatePersonaDefinitionInput(BaseModel):
     """更新人格定义工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     persona_id: str = Field(
         ...,
         description=(

app/agent/tools/impl/update_plugin_config.py

@@ -14,10 +14,8 @@ from app.log import logger
 class UpdatePluginConfigInput(BaseModel):
     """修改插件配置工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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 update. Use query_plugin_config first to inspect the current config.",

app/agent/tools/impl/update_rule_group.py

@@ -24,10 +24,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateRuleGroupInput(BaseModel):
     """更新过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     current_name: str = Field(..., description="Existing rule group name to update.")
     new_name: Optional[str] = Field(
         None,

app/agent/tools/impl/update_site.py

@@ -17,10 +17,8 @@ from app.utils.string import StringUtils
 class UpdateSiteInput(BaseModel):
     """更新站点工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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 update (can be obtained from query_sites tool)",

app/agent/tools/impl/update_site_cookie.py

@@ -13,10 +13,8 @@ from app.log import logger
 class UpdateSiteCookieInput(BaseModel):
     """更新站点Cookie和UA工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     site_identifier: int = Field(
         ...,
         description="Site ID to update Cookie and User-Agent for (can be obtained from query_sites tool)",

app/agent/tools/impl/update_subscribe.py

@@ -16,10 +16,8 @@ from app.schemas.types import EventType
 class UpdateSubscribeInput(BaseModel):
     """更新订阅工具的输入参数模型"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    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 update (can be obtained from query_subscribes tool)",

app/agent/tools/impl/update_system_settings.py

@@ -25,10 +25,8 @@ SettingValue = Optional[Union[list, dict, bool, int, float, str]]
 class UpdateSystemSettingsInput(BaseModel):
     """更新系统设置工具的输入参数模型。"""
 
-    explanation: str = Field(
-        ...,
-        description="Clear explanation of why this tool is being used in the current context",
-    )
+    explanation: Optional[str] = Field(None,
+        description="Clear explanation of why this tool is being used in the current context",)
     setting_key: str = Field(
         ...,
         description=(

app/agent/tools/manager.py

@@ -260,11 +260,16 @@ class MoviePilotToolsManager:
             # 调用工具的run方法。HTTP/MCP 工具调用不会经过 BaseTool._arun，
             # 因此这里也必须复用同一套返回值格式化和兜底截断逻辑。
             result = await tool_instance.run(**normalized_arguments)
-            return format_tool_result_for_agent(
-                result,
-                tool_name=tool_name,
-                max_chars=getattr(tool_instance, "result_max_chars", None),
-            )
+            
+            # 记录工具执行结果摘要日志
+            str_result = format_tool_result_for_agent(result, tool_name=tool_name, max_chars=getattr(tool_instance, "result_max_chars", None))
+            if len(str_result) > 500:
+                summary = str_result[:500] + f"...(已截断，总长度: {len(str_result)})"
+            else:
+                summary = str_result
+            logger.info(f"Agent工具 {tool_name} 执行完成，结果摘要: {summary}")
+            
+            return str_result
         except Exception as e:
             logger.error(f"调用工具 {tool_name} 时发生错误: {e}", exc_info=True)
             error_msg = json.dumps(

app/api/endpoints/history.py

@@ -3,7 +3,6 @@ import time
 from pathlib import Path
 from typing import List, Any, Optional
 
-import jieba
 from fastapi import APIRouter, Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import Session
@@ -24,6 +23,7 @@ from app.db.user_oper import (
 )
 from app.helper.progress import ProgressHelper
 from app.schemas.types import EventType
+from app.utils.jieba import cut as jieba_cut
 
 router = APIRouter()
 
@@ -272,7 +272,7 @@ async def transfer_history(
                 db, title=like_pattern, page=page, count=count, status=status, wildcard=True
             )
         else:
-            words = jieba.cut(title, HMM=False)
+            words = jieba_cut(title, HMM=False)
             like_pattern = "%".join(words)
             total = await TransferHistory.async_count_by_title(
                 db, title=like_pattern, status=status

app/api/endpoints/message.py

@@ -15,6 +15,7 @@ from app.db.models import User
 from app.db.models.message import Message
 from app.db.user_oper import get_current_active_superuser
 from app.helper.service import ServiceConfigHelper
+from app.helper.webpush import is_webpush_subscription_gone
 from app.log import logger
 from app.modules.wechat.WXBizMsgCrypt3 import WXBizMsgCrypt
 from app.schemas.types import MessageChannel
@@ -218,8 +219,7 @@ async def subscribe(
     客户端webpush通知订阅
     """
     subinfo = subscription.model_dump()
-    if subinfo not in global_vars.get_subscriptions():
-        global_vars.push_subscription(subinfo)
+    global_vars.push_subscription(subinfo)
     logger.debug(f"通知订阅成功: {subinfo}")
     return schemas.Response(success=True)
 
@@ -244,5 +244,7 @@ def send_notification(
             )
         except WebPushException as err:
             logger.error(f"WebPush发送失败: {str(err)}")
+            if is_webpush_subscription_gone(err) and global_vars.remove_subscription(sub):
+                logger.info(f"已移除失效WebPush订阅: {sub.get('endpoint')}")
             continue
     return schemas.Response(success=True)

app/api/endpoints/plugin.py

@@ -251,6 +251,12 @@ async def install(
     # 首先检查插件是否已经存在，并且是否强制安装，否则只进行安装统计
     plugin_helper = PluginHelper()
     if not force and plugin_id in PluginManager().get_plugin_ids():
+        if repo_url:
+            compatible_message = await plugin_helper.async_get_plugin_system_version_check_message(
+                plugin_id, repo_url
+            )
+            if compatible_message:
+                return schemas.Response(success=False, message=compatible_message)
         await plugin_helper.async_install_reg(pid=plugin_id, repo_url=repo_url)
     else:
         # 插件不存在或需要强制安装，下载安装并注册插件
@@ -319,10 +325,13 @@ def plugin_form(
     render_mode, _ = plugin_instance.get_render_mode()
     try:
         conf, model = plugin_instance.get_form()
+        stored_config = plugin_manager.get_plugin_config(plugin_id)
+        # Merge stored config with defaults so all keys exist for v-show evaluation
+        merged_model = {**model, **(stored_config or {})}
         return {
             "render_mode": render_mode,
             "conf": conf,
-            "model": plugin_manager.get_plugin_config(plugin_id) or model,
+            "model": merged_model,
         }
     except Exception as e:
         logger.error(f"插件 {plugin_id} 调用方法 get_form 出错: {str(e)}")