database-operation

数据库操作

所有脚本路径均相对于此技能文件。

使用 scripts/mp-db.py 访问所有数据库。不要从提示词中提取数据库密码、API 令牌或完整的 PostgreSQL DSN。脚本会读取 MoviePilot 本地设置，并在内部连接 SQLite 或 PostgreSQL。

范围与边界

此技能用于直接执行 SQL。它由 Python 脚本实现，适用于 Agent 必须检查记录、运行数据统计、修复卡住的状态，或执行明确请求的数据库更新时。

从 MoviePilot 程序目录使用项目运行时运行随附脚本，例如：

cd <MOVIEPILOT_ROOT>
python skills/database-operation/scripts/mp-db.py tables

Agent 命令环境会在可用时将 python 路由到项目专用的 moviepilot-python 入口；否则会回退到项目或 Docker 的 VENV_PATH Python。

运行时会为复制的技能设置 MOVIEPILOT_ROOT。如果直接从 <CONFIG_PATH>/agent/skills/ 运行复制的脚本，请先将该变量设为程序目录；否则，辅助程序会提示如何迁移它。请使用项目运行时，而不是系统的 python3。

优先使用更安全的产品操作入口：

请求	首选技能
MoviePilot 常规产品操作	moviepilot-api 结构化操作
结构化 API 目录之外的操作	更具体的技能，或明确说明不支持
斜杠命令或插件／系统命令分发	command-dispatch
手动整理文件	organize-files
重试失败的传输历史记录	transfer-failed-retry

仅在数据访问或修改的最后兜底时使用此技能。它可以通过随附脚本运行 SELECT、INSERT、UPDATE、DELETE 和修改架构的语句，但广泛或具有破坏性的写入仍需用户明确授权。

系统设置有两个受管理的数据源，通常不应在此处编辑：

• 运行时 Settings 变量由 moviepilot-api 的 config.system.get / config.system.update 操作查询和更新；更新会执行类型转换并持久化到 app.env。
• SystemConfigKey 值存储在数据库的 systemconfig 表中，但应优先使用相同的 API 操作，因为它们会校验已注册的键、插件修改准入、值规范化、机密信息脱敏和配置变更事件。

仅当受管理 API 无法完成操作且已获得明确授权时，才直接对 systemconfig 执行 SQL 修复。脚本会阻止任何涉及 systemconfig 的语句，直到你传入 --show-secrets；因此请先检查确切的行，避免广泛写入，并验证受管理 API 能读取修复后的值。

命令

列出表：

python scripts/mp-db.py tables

显示表结构：

python scripts/mp-db.py schema downloadhistory

运行读取查询：

python scripts/mp-db.py query "SELECT COUNT(*) AS total FROM downloadhistory"

从标准输入或文件读取 SQL：

python scripts/mp-db.py query --file /path/to/query.sql

运行写入语句：

python scripts/mp-db.py write "UPDATE subscribe SET state = 'S' WHERE id = 123"

为保持兼容性，也支持 query --write，但对于 INSERT、UPDATE、DELETE 和架构变更，请优先使用 write 子命令。

SQLite 还会在执行每条语句时检查实际访问的表，包括单引号括起的表名以及通过视图进行的读取。该语句结束后会移除临时授权器。PostgreSQL 则会保留下文所述的标识符检查。

无论读取还是写入模式，涉及 systemconfig 的语句都会被拒绝，除非你添加 --show-secrets：

python scripts/mp-db.py query "SELECT key, value FROM systemconfig WHERE key = 'TMDB_API_KEY'" --show-secrets

此门控针对整张表，而非单个列，因此即使只是统计行数或列出键，也需要对 systemconfig 使用该标志。请改用 moviepilot-api 的 config.system.get 读取常规设置，它会为你脱敏机密信息；仅在明确授权的修复操作中传入此标志。

工作流

1. 对于常规产品工作流，优先使用现有的 MoviePilot 工具或 API。
2. 仅当没有现有工具能够处理请求时，才使用此技能直接检查数据库。
3. 对于未知的架构，先运行 tables，然后运行 schema <table>。
4. 对于 SELECT 查询，执行时使用精简的投影，并在读取行时明确指定 LIMIT。
5. 对于 INSERT、UPDATE、DELETE、DROP、ALTER、TRUNCATE、CREATE 或 REPLACE，使用 write，并报告受影响的行数。

内置安全机制

• query 默认为只读模式。
• write 会直接执行数据更新和架构变更语句。
• query --write 仍可用作写入语句的兼容别名。
• 单次调用中的多条 SQL 语句会被拒绝。
• SQL 字面量、带引号的标识符和注释中的关键字及分号，不会将查询变为写入操作或多语句请求。未闭合的词法结构仍然无效。
• 如果纯 SELECT 查询中没有 LIMIT，系统会默认添加 LIMIT 100。
• systemconfig 会汇总每个实例级别的 API 密钥、Cookie 和密码，因此在传入 --show-secrets 之前，该表不可读也不可写。系统可识别带引号的标识符和带架构限定的名称，因此给表起别名也无法绕过此限制。
• 其他表不受限制。site 和插件数据仍包含各站点的凭据，因此请使用精简的投影，而不要选择整行。
• 结果会按存储内容原样返回。必要时，Agent 可在内部使用敏感值，但除非用户明确要求查看该值，否则不得在最终面向用户的回复中复述秘密。

安全规则

1. 如果用户尚未明确授权具体变更，在执行破坏性或范围较大的写入操作前，必须先确认。
2. 执行 DELETE、DROP 或 TRUNCATE 等破坏性操作前，建议先备份。
3. 除非用户明确希望影响所有行，否则绝不在没有 WHERE 子句的情况下运行 UPDATE 或 DELETE。
4. 工具输出中可能包含原始秘密、Cookie、通行密钥、哈希密码、OTP 秘密、API 密钥或令牌。仅将其用于请求的操作，除非用户明确要求，否则避免在最终回复中复述。对于可由其他界面报告的值，绝不要添加 --show-secrets 来扩大搜索范围。
5. 保持输出简短。对大型结果进行概述，而不要直接倾倒全部内容。

核心表

tables 会返回当前实例中存在的表。下方目录涵盖 MoviePilot 的所有 ORM 表以及 Alembic 元数据。始终以实时的 schema <table> 结果为准。

agentchat

• 用途：存储 Web Agent 和消息渠道的会话索引、标题、预览及消息快照。
• 实用查询：按用户、会话或更新时间追踪 Agent 历史记录或上下文恢复情况。
• 写入边界：此表由 Agent 对话服务管理；不要改写消息 JSON、计数器或所有权信息。
• 列：id、session_id、client_session_id、user_id、username、channel、source、original_chat_id、title、preview、agent_messages、display_messages、message_count、created_at、updated_at

agentinvocation

• 用途：持久化记录 Agent 写入调用的身份和最近观察到的结果，包括已确认的异步提交。
• 适用查询：检查指定主体和会话的运行中、未知、待处理、成功或失败回执；诊断写入中断时比较时间戳。
• 写入边界：由宿主的原子认领与协调流程管理。切勿更改 ID、指纹、认领令牌或状态来绕过重复保护。运行中和未知记录属于恢复状态；常规保留策略不会删除这些记录。待处理表示提交已确认，不代表外部任务已完成。此处不会存储原始参数和工具输出。
• 列：id、principal_id、session_id、invocation_id、tool_name、arguments_digest、claim_token、status、summary、created_at、updated_at

agenttask

• 用途：存储一次性或定期 Agent 任务定义、触发器和最近一次执行摘要。
• 适用查询：检查任务归属、启用状态、cron/run_at 设置和最近一次结果。
• 写入边界：通过 Agent 任务 API 创建、更新、启用、停用或删除任务。
• 列：id、name、content、trigger_type、cron_expression、run_at、enabled、user_id、username、session_id、channel、source、original_chat_id、last_status、last_run_at、last_result、last_run_id、run_count、created_at、updated_at

agenttaskrun

• 用途：存储每次 Agent 任务执行的输入快照、状态、时间戳和结果。
• 适用查询：审计单次运行，或通过 task_id、run_id 和触发来源关联故障。
• 写入边界：执行证据由任务运行器管理；切勿伪造记录或编辑运行状态。
• 列：id、run_id、task_id、trigger_source、name、content、trigger_type、cron_expression、run_at、user_id、username、session_id、channel、message_source、original_chat_id、status、started_at、finished_at、result

alembic_version

• 用途：记录当前已应用于数据库的 Alembic 迁移版本。
• 适用查询：诊断启动迁移失败或数据库与代码版本不匹配的问题。
• 写入边界：切勿直接编辑；只能通过 Alembic 升级或回滚版本。
• 列：version_num

downloadfailure

• 用途：存储失败下载的稳定指纹、媒体／种子上下文、错误和重试计划。
• 适用查询：分析失败原因、重试次数、下次重试时间以及受影响的媒体或站点。
• 写入边界：由下载失败补偿流程管理；通过其业务 API 重试或清理记录。
• 列：id、fingerprint、type、title、year、media_source、media_id、seasons、episodes、site、site_name、torrent_id、torrent_name、torrent_size、downloader、source、error_message、retry_count、first_failed_at、last_failed_at、next_retry_at

downloadfiles

• 用途：将下载器任务哈希映射到完整路径、保存目录、相对文件和活动状态。
• 适用查询：按下载器／download_hash 查找任务文件，或诊断保存路径关联。
• 写入边界：由下载和传输流程维护；请勿手动更改状态或路径映射。
• 列：id、downloader、download_hash、fullpath、savepath、filepath、torrentname、state

downloadhistory

• 用途：存储已提交下载的媒体身份、种子、下载器、用户和识别上下文。
• 常用查询：查看下载历史，或追溯媒体身份或哈希值的来源。
• 写入边界：由下载用例写入；通过下载历史 API 删除或更正记录。
• 列：id、path、type、title、year、media_source、media_id、music_type、seasons、episodes、image、poster、downloader、download_hash、torrent_name、torrent_description、torrent_site、userid、username、channel、date、note、media_category_id、media_category、classification_rule_id、classification_policy_revision、classification_source、episode_group、custom_words

mediaserveritem

• 用途：存储从媒体服务器库投影而来的本地索引和规范媒体身份。
• 常用查询：检查媒体库是否包含项目，以及服务器／媒体库／路径位置和季节信息。
• 写入边界：这是可重建的投影；写入和清理由媒体服务器同步负责。
• 列：id、server、library、item_id、item_type、title、original_title、year、media_source、media_id、path、seasoninfo、note、lst_mod_date

message

• 用途：存储传入和传出的消息、频道、内容、附件、用户和时间戳。
• 常用查询：分页查看通知历史、区分消息方向，或按来源追踪重复消息。
• 写入边界：由消息和通知服务写入；通过消息 API 或保留期限任务进行清理。
• 列：id、channel、source、mtype、title、text、image、poster、link、userid、reg_time、action、note

outboxmessage

• 用途：存储与业务事务原子提交、对外可见的副作用意图。
• 常用查询：诊断待处理／处理中／失败状态、租约、尝试次数和最近一次错误。
• 写入边界：由 Outbox Dispatcher 状态机负责；切勿手动标记未投递事件已完成或将其删除。
• 列：id、event_key、topic、payload_version、payload、status、attempt、next_retry_at、lease_until、last_error、created_at、completed_at

passkey

• 用途：存储 WebAuthn／PassKey 凭据、公钥、签名计数器和激活状态。
• 常用查询：排查授权认证问题，例如所有权、激活状态和上次使用时间。
• 写入边界：涉及安全；仅通过 PassKey API 管理，切勿泄露凭据材料。
• 列：id、user_id、credential_id、public_key、sign_count、name、aaguid、created_at、last_used_at、is_active、transports

plugindata

• 用途：按 plugin_id 和 key 隔离存储由插件所有的 JSON 值。
• 常用查询：针对明确指定的插件和键，诊断持久化或迁移问题。
• 写入边界：这些值由插件所有；优先使用插件功能或插件数据 API。
• 列：id、plugin_id、key、value

pluginidentity

• 用途：存储实体插件包的可信来源、载荷来源、版本、接收回执和 CAS 修订号。
• 常用查询：审计来源绑定、软件包生成、载荷应用或身份冲突。
• 写入边界：插件供应链状态仅由安装和更新事务负责。
• 列：id、plugin_id、normalized_plugin_id、trusted_source_type、trusted_source_key、binding_basis、payload_source_type、payload_source_key、declared_version、package_generation、declared_metadata、payload_receipt、revision、created_at、updated_at、bound_at、payload_applied_at

plugininstallation

• 用途：存储插件安装阶段、成员关系目标、身份修订版本和备份状态。
• 有用的查询：诊断中断的安装、回滚条件，以及软件包或备份是否存在。
• 写入边界：由插件安装状态机管理；切勿手动推进阶段或覆盖证据。
• 列：id、transaction_id、plugin_id、phase、membership_before、host_enabled_before、membership_target、identity_before_revision、identity_target_revision、package_existed、persistent_backup_existed、created_at、updated_at、schema_version

plugininstance

• 用途：每个共享来源插件运行时实例对应一行，涵盖克隆和宿主插件本身（instance_id 等于 source_plugin_id，因此相等表示宿主插件，不相等则表示克隆），并存储该实例的显示覆盖项、自身的日志级别覆盖项及该覆盖项的过期时间，以及插件自身的配置数据。只有该行存在时克隆才存在，因此删除该行会卸载克隆并丢弃其配置。
• 有用的查询：诊断克隆的命名和归属、查看插件或其克隆的配置，或查找当前覆盖全局日志级别的实例及覆盖项的过期时间。
• 写入边界：由插件实例、插件配置和插件日志级别 API 管理；切勿直接编辑数据行。
• 列：id、instance_id、source_plugin_id、plugin_name、plugin_desc、plugin_icon、is_default_target、is_enabled、log_level、log_expires_at、config_data、created_at、updated_at

searchsession

• 用途：存储一个尚未完成的订阅搜索任务的页面游标和待处理候选项，不含站点凭据；任务结束时删除，超过 14 天未更新时清理。
• 有用的查询：通过 task_id、version 和 updated_at 诊断暂停或恢复的分页搜索。
• 写入边界：仅在队列任务租约下通过版本 CAS 写入；切勿编辑负载，否则可能跳过页面或重新提交候选项。
• 列：id、task_id、version、payload、updated_at

site

• 用途：存储私有 Tracker 的 URL、RSS、凭据、速率限制、代理状态和下载器绑定。
• 有用的查询：在尽量少暴露凭据的情况下，检查启用状态、域名、速率限制或下载器绑定。
• 写入边界：包含 Cookie、API 密钥和令牌；请通过站点 API 管理。
• 列：id、name、domain、url、pri、rss、cookie、ua、apikey、token、proxy、filter、render、public、note、limit_interval、limit_count、limit_seconds、timeout、is_active、lst_mod_date、downloader

siteicon

• 用途：缓存站点名称、域名、图标 URL 和 Base64 图标内容。
• 有用的查询：诊断图标缺失、域名映射错误或缓存生成问题。
• 写入边界：由站点图标同步流程管理的可重建缓存；不建议直接写入。
• 列：id、name、domain、url、base64

sitestatistic

• 用途：汇总站点请求的成功次数、失败次数、耗时、最新状态和诊断备注。
• 有用的查询：比较站点可用性、失败率和最近一次访问状态。
• 写入边界：由站点访问统计流程累积；切勿编辑计数器来掩盖运行时行为。
• 列：id、domain、success、fail、seconds、lst_state、lst_mod_date、note

siteuserdata

• 用途：存储站点账号等级、流量、分享率、做种和未读消息数据。
• 常用查询：检查账号状态、流量趋势、做种量和最近一次采集错误。
• 写入边界：这是一个由同步刷新的站点抓取投影；请勿直接编辑。
• 列：id、domain、name、username、userid、user_level、join_at、bonus、upload、download、ratio、seeding、leeching、seeding_size、leeching_size、seeding_info、message_unread、message_unread_contents、err_msg、updated_day、updated_time

subscribe

• 用途：存储生效中的电影、电视剧或音乐订阅、筛选条件、进度和下载目标。
• 常用查询：检查状态、缺失的剧集／曲目、画质规则、站点范围和匹配进度。
• 写入边界：通过订阅 API 创建、更新、搜索或删除，以保持状态机的一致性。
• 列：id、activity_key、identity_key、name、year、type、search_interval、keyword、media_source、media_id、music_type、total_tracks、downloaded_tracks、season、poster、backdrop、vote、description、filter、include、exclude、quality、resolution、effect、audio_quality、audio_format、min_bitrate、min_bit_depth、min_sample_rate、total_episode、start_episode、lack_episode、note、state、last_search、last_update、date、username、sites、downloader、best_version、best_version_full、current_priority、current_audio_format、current_bitrate、current_bit_depth、current_sample_rate、episode_priority、save_path、search_imdbid、manual_total_episode、custom_words、media_category_id、media_category、filter_groups、episode_group

subscribeactivity

• 用途：存储结构化的订阅业务事件，以及功能升级后记录的可恢复搜索轮次进度。
• 常用查询：通过经过身份验证的订阅活动 API 检查事件摘要、冻结的筛选规则、安全的资源决策和重试次数。
• 写入边界：由订阅事务和活动观测负责维护。切勿通过解析运行时日志重建事件，也不要直接修改已提交下载的事实记录。
• 列：id、activity_key、event_id、kind、source、status、started_at、finished_at、counts、details、tracking
• activity_key 将原始订阅与其已完成的历史记录关联起来，不受整数 ID 复用影响。tracking 包含内部哈希去重键，不会包含在 API 响应中。

subscribehistory

• 用途：存储已完成或归档订阅的快照及其最终筛选状态。
• 常用查询：审计历史订阅、媒体身份、完成条件和筛选配置。
• 写入边界：由订阅完成和归档流程生成；请通过对应的业务 API 恢复或删除。
• 列：id、activity_key、name、year、type、search_interval、keyword、media_source、media_id、music_type、total_tracks、season、poster、backdrop、vote、description、filter、include、exclude、quality、resolution、effect、audio_quality、audio_format、min_bitrate、min_bit_depth、min_sample_rate、total_episode、start_episode、date、username、sites、best_version、best_version_full、current_priority、current_audio_format、current_bitrate、current_bit_depth、current_sample_rate、episode_priority、save_path、search_imdbid、custom_words、media_category_id、media_category、classification_rule_id、classification_policy_revision、classification_source、filter_groups、episode_group

subscriptionsearchbatch

• 用途：存储持久化的订阅搜索批次、来源、汇总状态、计数和取消请求。
• 实用查询：检查用户可见的搜索进度、恢复状态、取消情况和终态结果。
• 写入边界：由订阅搜索编排负责；通过订阅 API 创建和取消批次。
• 列：id、batch_id、source、state、priority、total_count、finished_count、failed_count、cancelled_count、skipped_count、cancel_requested、created_at、updated_at、started_at、finished_at、last_error

subscriptionsearchtask

• 用途：为每个批次和订阅存储一个持久化的订阅搜索任务，以及租约和执行阶段。
• 实用查询：诊断已排队、运行中、失败、已取消或已恢复的任务及其当前站点。
• 写入边界：仅由搜索队列租约状态机推进；切勿手动重写租约或终态。
• 列：id、task_id、batch_id、subscription_id、active_key、source、priority、position、state、phase、current_site_id、pending_site_ids、attempt_count、cancel_requested、lease_owner、lease_token、lease_expires_at、available_at、created_at、updated_at、started_at、finished_at、last_error

subscriptionsitebudget

• 用途：存储每个站点的订阅搜索并发数、冷却时间、健康状况和公平性状态。
• 实用查询：诊断站点负载、冷却延期、近期失败和活跃搜索的归属情况。
• 写入边界：由订阅站点预算协调器负责；不要通过直接执行 SQL 清除冷却时间或计数器。
• 列：id、site_id、lease_owner、lease_token、lease_expires_at、next_allowed_at、consecutive_failures、success_streak、last_outcome、last_error、updated_at

systemconfig

• 用途：存储按 SystemConfigKey 索引的 JSON 业务配置值。
• 实用查询：仅当托管设置 API 行为异常时，验证实际存储的值。
• 写入边界：优先使用 config.system.get/update；直接写入会绕过验证、事件和插件准入。
• 列：id、key、value

transferexecutionstep

• 用途：存储每项持久化传输操作的意图、尝试标识、状态和结果证据。
• 实用查询：按 task_id 或 operation_id 诊断卡住、失败或重复的步骤。
• 写入边界：由传输执行状态机和租约 CAS 负责；切勿手动强制状态转换。
• 列：id、task_id、operation_id、checkpoint_fingerprint、ordinal、phase、kind、state、attempt_token、attempt_count、intent_version、intent_payload、result_version、result_payload、last_error、prepared_at、started_at、completed_at、updated_at

transferhistory

• 用途：存储传输来源、目标、模式、媒体标识、下载关联和结果。
• 实用查询：查看成功/失败历史、目标路径、媒体分类和下载关联。
• 写入边界：由传输结算写入；通过传输历史业务 API 删除或重试。
• 列：id、transfer_task_id、transfer_settlement_revision、src、src_storage、src_fileitem、dest、dest_storage、dest_fileitem、mode、type、media_category_id、category、classification_rule_id、classification_policy_revision、classification_source、title、year、media_source、media_id、music_type、total_tracks、audio_format、audio_lossless、bit_depth、sample_rate、bitrate、seasons、episodes、image、downloader、download_hash、status、errmsg、retry_count、auto_paused、failure_stage、recovery_action、cleanup_status、cleanup_error、date、files、episode_group

transferpending

• 用途：持久化存储待处理的传输输入、计划、检查点、租约、重试和人工审核状态。
• 适用查询：诊断重启恢复、租约过期、retry_wait、终止失败或人工审核。
• 写入边界：核心持久化状态机仅由规划、执行、重试和审核服务推进。
• 列：id、task_id、storage、src_path、created_at、state、updated_at、last_error、input_version、planning_input、input_fingerprint、checkpoint_version、checkpoint_payload、planned_at、lease_owner、lease_token、lease_expires_at、heartbeat_at、attempt_count、execution_state、execution_version、execution_payload、execution_fingerprint、retry_generation、retry_count、retry_due_at、retry_requested_by、retry_reason、settlement_revision、terminal_history_id、manual_review_revision、reviewed_at、reviewed_by、review_reason、review_decision

transfersettlementreceipt

• 用途：存储不可变的终止结算收据，并为每个传输任务维护连续的修订号。
• 适用查询：验证历史记录、待处理项删除和执行指纹是否已可靠结算。
• 写入边界：用于幂等性和审计凭证；仅追加修订，绝不覆盖或删除旧收据。
• 列：id、task_id、history_id、settlement_revision、outcome、execution_fingerprint、lease_token、history_status、src、src_storage、pending_deleted、error、created_at、updated_at

user

• 用途：存储用户账户、密码哈希、管理员状态、OTP、权限和偏好设置。
• 适用查询：经授权诊断账户状态、权限或身份验证配置。
• 写入边界：涉及安全；请通过用户、权限、密码和双重验证 API 管理。
• 列：id、name、email、hashed_password、is_active、is_superuser、avatar、is_otp、otp_secret、permissions、settings、notification_identity

userconfig

• 用途：按用户名和键隔离存储每位用户的 JSON 配置。
• 适用查询：检查 UI 偏好、消息清除游标或其他个性化状态。
• 写入边界：通过所属用户或消息 API 修改，以保留键语义。
• 列：id、username、key、value

widgetregistration

• 用途：按用户和安装信息存储有过期时间的只读小组件授权；仅存储专用 Bearer 的摘要，绝不存储原始密钥或主登录令牌。
• 适用查询：经授权诊断某位用户的安装归属、过期时间或已撤销的小组件访问权限；绝不泄露凭证摘要，也不盘点其他用户的安装信息。
• 写入边界：涉及安全；仅通过经过身份验证的小组件 API 注册、轮换或撤销。绝不插入授权、更改归属或过期时间，也不将摘要复制到登录凭证中。
• 列：id、registration_id、installation_id、user_id、owner、secret_digest、expires_at

workflow

• 用途：存储工作流定义、触发器、操作图、执行上下文和运行时状态。
• 适用查询：检查定时/事件工作流、暂停状态、当前操作、运行次数和失败情况。
• 写入边界：通过工作流 API 创建、修改、运行、暂停或重置。
• 列：id、name、description、timer、trigger_type、event_type、event_conditions、state、current_action、result、run_count、actions、flows、context、execution_config、execution_state、add_time、last_time

数据库操作约定

• tables：arguments={} 列出当前数据库中的表。
• schema：arguments={"table_name":"downloadhistory"}；table_name 必须来自 tables。
• query：arguments={"sql":"SELECT ...","limit":100,"write":false}；必须且只能提供 sql 和 file 其中之一。默认允许 SELECT/WITH/EXPLAIN。
• write：arguments={"sql":"UPDATE ... WHERE ..."}；必须且只能提供 sql 和 file 其中之一，且只能包含一条语句。
• file 是 MoviePilot 进程可读取的本地 SQL 路径。MCP 客户端通常会直接发送 sql。

使用实时的 schema 结果，不要根据旧文档猜测列名。将 media_source 和 media_id 视为不可拆分的身份组合。

常用查询

下载总数：

SELECT COUNT(*) AS total FROM downloadhistory

最近的下载历史：

SELECT title, year, type, torrent_site, date FROM downloadhistory ORDER BY id DESC LIMIT 10

失败的传输：

SELECT id, title, src, errmsg, date FROM transferhistory WHERE status = 0 ORDER BY id DESC LIMIT 10

有效订阅：

SELECT name, year, type, season, state, lack_episode FROM subscribe WHERE state = 'R' LIMIT 50

站点上传 / 下载统计：

SELECT name, domain, upload, download, ratio, bonus, seeding, user_level FROM siteuserdata ORDER BY upload DESC LIMIT 50

媒体库统计：

SELECT server, library, COUNT(*) AS count FROM mediaserveritem GROUP BY server, library

站点访问成功率：

SELECT domain, success, fail, ROUND(success * 100.0 / (success + fail), 1) AS success_rate FROM sitestatistic WHERE success + fail > 0 ORDER BY success_rate DESC LIMIT 50

插件数据键：

SELECT plugin_id, key FROM plugindata ORDER BY plugin_id, key LIMIT 100

SQL 方言说明

功能	SQLite	PostgreSQL
布尔值	0 / 1	false / true
字符串拼接	`
当前时间	datetime('now')	NOW()
JSON 访问	json_extract(col, '$.key')	col->>'key'
不区分大小写的匹配	LIKE	ILIKE

故障排除

• 缺少依赖：在 MoviePilot 项目环境中运行，以确保可使用 SQLAlchemy 和数据库驱动程序。
• 连接失败：使用 moviepilot doctor 验证 MoviePilot 配置。
• 未找到表：运行 python scripts/mp-db.py tables，然后使用 schema 检查该表。