MoviePilot Torrent Cache API 全解析：种子缓存查询、刷新、重识别与删除的完整操作指南

后端AI AgentMCP 服务AI 技能【免费下载链接】MoviePilotNAS媒体库自动化管理工具项目地址https://gitcode.com/gh_mirrors/mo/MoviePilot点击查看免费下载本文是 MoviePilotNAS 媒体库自动化管理工具中Torrent Cache种子缓存API 的技术指南围绕torrent.cache.*命名空间下的 5 个操作展开查询get、刷新refresh、重新识别reidentify、单条删除delete与全量清理clear。它面向两类读者一类是通过moviepilot_api网关调用该能力的 Agent / LLM 应用开发者另一类是希望理解种子缓存底层存储与识别机制的 MoviePilot 开发者。读完本文你将掌握每个操作的 HTTP 路由、参数契约、策略效果policy effect与真实调用方式并能结合源码理解缓存如何按订阅模式RSS/爬虫与媒体类型影视/音乐独立存储、种子 hash 如何计算、重新识别如何影响下游订阅匹配。Torrent Cache 是什么一次说清它的职责边界在 MoviePilot 中种子缓存torrent cache是订阅匹配的数据底座。系统按配置的订阅站点抓取或订阅最新资源后将候选种子连同其识别出的媒体信息暂存为缓存供订阅搜索、匹配与后续下载流程复用。理解它的关键前提是两点缓存来源由订阅模式决定subscribe_mode为rss时使用 RSS 订阅缓存为spider时使用爬虫缓存。该逻辑在 种子缓存读取端点 中通过get_api_runtime_config_snapshot().subscribe_mode判定并分别读取rss或spider类型的缓存。影视与音乐缓存分离存储缓存文件按媒体类型拆分为影视与音乐两份独立存储split_cache_contexts 依据torrent.category是否等于MediaType.MUSIC做拆分写回时分别落盘cache_files()返回的文件对。这意味着对缓存做删除、重识别等写操作时两类缓存会被分别持久化。Torrent Cache API 正是围绕这套缓存体系暴露的 5 个受控操作全部经由moviepilot_api网关按固定路由执行且每个操作都声明了明确的策略效果policy effect供 Agent 判断是否需要用户确认。操作总览操作 ID方法路径策略效果用途torrent.cache.getGET/api/v1/torrent/cachesafe_read查看缓存种子及其识别的媒体身份torrent.cache.refreshPOST/api/v1/torrent/cache/refreshexternal_side_effect从配置的 RSS / 爬虫源刷新种子缓存torrent.cache.reidentifyPOST/api/v1/torrent/cache/reidentify/{domain}/{torrent_hash}reversible_write重算或替换单条缓存种子的媒体身份torrent.cache.deleteDELETE/api/v1/torrent/cache/{domain}/{torrent_hash}destructive_write按站点域名与缓存 hash 删除单条缓存torrent.cache.clearDELETE/api/v1/torrent/cachedestructive_write清空全部种子缓存路由表在 app/agent/policy/api.py 中登记策略效果声明在同文件 L508-L518并与 API 表面审计文档 中的路由清单一一对应。逐个操作详解torrent.cache.get查看缓存与已识别的媒体身份方法/路径GET /api/v1/torrent/cache策略效果safe_read只读无需确认参数path_params、query、body均为空。该操作返回当前订阅模式下全部缓存的种子上下文及其媒体识别结果。从 端点实现 可以看到它做了三件事按订阅模式读取缓存RSS 或爬虫对每条缓存计算 hash 并解析媒体身份resolve_media_identity聚合返回count种子总数、sites站点数与data明细数组。每条明细包含的关键字段字段说明hash种子缓存 hashtitle description的 MD5domain来源站点域名title/description种子标题与描述size/pubdate/site_name大小、发布时间、站点名media_name/media_year/media_type识别出的媒体名、年份、类型media_source/media_id媒体元数据源标识与其原生 ID两者必须成对使用music_type音乐实体类型recording / albumseason_episode/resource_term季集信息与资源关键词enclosure/page_url下载地址与详情页poster_path/backdrop_path海报与背景图torrent.cache.refresh从 RSS / 爬虫源刷新缓存方法/路径POST /api/v1/torrent/cache/refresh策略效果external_side_effect对外部站点产生副作用通常需要确认参数三者均为空。该操作触发一次全量缓存刷新。底层调用 TorrentsChain.refresh()按订阅模式读取影视/音乐两份缓存 → 过滤无效种子TorrentHelper().is_invalid校验 enclosure→ 对配置站点SystemConfigKey.RssSites或传入站点列表重新抓取/订阅最新资源。端点返回形如缓存刷新完成共刷新 N 个站点M 个种子的汇总信息。torrent.cache.reidentify重算单条缓存的媒体身份方法/路径POST /api/v1/torrent/cache/reidentify/{domain}/{torrent_hash}策略效果reversible_write可回滚的写入path_paramsdomain*string站点主机名或域名用于匹配与请求torrent_hash*string由torrent.cache.get返回的、针对某站点条目的缓存 hash。query均为可选media_idstring|null源端原生媒体 ID必须与搜索返回的media_source精确配对media_sourceMediaSource|null元数据源标识保留与media_id一同返回的精确值music_typestring(recording,album)|null音乐身份级别支持的取值为 recording、albumartist 仅可浏览。body无。这是 5 个操作中唯一带业务逻辑的操作其核心实现在 TorrentCacheRecognitionService.execute()。执行流程如下定位缓存条目校验domain存在并按HashUtils.md5(title description) torrent_hash找到目标Context判定音乐实体当缓存媒体类型为音乐、元信息为MetaMusic、分类为music、或显式传入音乐数据源/音乐类型时走音乐识别分支。音乐重识别仅允许使用音乐元数据源且music_type只支持recording/album媒体识别若同时提供media_source与media_id调用media_chain.async_recognize_media按显式 ID 识别否则调用async_recognize_by_meta按标题/描述解析此时media_source、media_id必须同时提供或同时缺省否则返回媒体来源和媒体 ID 必须同时提供持久化识别结果写回media_info后将合并缓存拆分为影视/音乐两份并分别落盘返回结果三元组(success, message, data)data包含识别后的media_name、media_year、media_type、media_source、media_id、music_type兼容旧插件的 HTTP 响应结构。torrent.cache.delete按域名与 hash 删除单条缓存方法/路径DELETE /api/v1/torrent/cache/{domain}/{torrent_hash}策略效果destructive_write破坏性写入需要确认且不可恢复path_paramsdomain*string、torrent_hash*string含义同上。query / body无。实现要点见 delete_cache 端点删除前先校验站点存在再按 hash 过滤掉目标条目若过滤前后数量不变则返回未找到指定的种子删除后同样按影视/音乐拆分回写缓存文件。注意删除只影响缓存不影响站点上真实存在的种子后续refresh可能重新抓取同一资源。torrent.cache.clear清空全部种子缓存方法/路径DELETE /api/v1/torrent/cache策略效果destructive_write参数三者均为空。直接调用 TorrentsChain.async_clear_torrents() 清空缓存。适用场景包括缓存数据过期、订阅站点配置大改、需要强制全量重建缓存等。清空后建议立即执行torrent.cache.refresh重建。网关调用约定与策略模型以上操作不是任意 HTTP 客户端可直接调用的 REST 接口而是通过moviepilot_api网关暴露的结构化 Agent 操作。调用时只需提供operation_id、path_params、query、body四要素HTTP 方法与路径、当前用户认证令牌、授权与确认策略均由宿主侧完成。调用模板如下来源SKILL.md{ operation_id: torrent.cache.reidentify, path_params: {domain: example.com, torrent_hash: md5-of-title-plus-description}, query: {media_source: tmdb, media_id: 12345, music_type: album}, body: {} }几条硬性规则参数归桶路径占位符domain、torrent_hash等放path_paramsGET 过滤与控制值放queryPOST/PUT/PATCH 的请求模型放body。不要把query字段塞进path_params也不要发送未声明字段。成对复用标识media_source与media_id必须成对出现并保留搜索/详情返回的精确值音乐场景还要保留music_typerecording|album|artistartist 仅可浏览。策略效果决定确认与恢复safe_read如torrent.cache.get只读无需确认结果敏感度为PRIVATEexternal_side_effect如torrent.cache.refresh对外部站点产生副作用须取得确认后执行reversible_write如torrent.cache.reidentify可回滚写入源码登记了RecoveryMode.RECONCILE恢复模式destructive_write如torrent.cache.delete/torrent.cache.clear破坏性写入恢复模式为RecoveryMode.NONE执行前必须确认。响应检查以success、execution_outcome、错误信息与空结果为准unknown结果不得重试写操作应先用读操作torrent.cache.get核实实际状态。超级用户限定从端点实现可见所有 Torrent Cache 端点均依赖get_current_active_superuser(_async)鉴权仅管理员可操作。源码级原理hash 计算与缓存落盘缓存 hashtitle description的 MD5无论是删除、重识别还是 get 返回的hash其算法完全一致HashUtils.md5(f{context.torrent_info.title}{context.torrent_info.description})见 cache.py 与 torrent.py。这意味着hash 是确定性的相同站点的相同种子在多次查询中 hash 不变可直接缓存复用修改标题或描述会改变 hash从而产生新条目。影视/音乐分离持久化缓存读取通过 async_get_torrents() 完成分别加载影视缓存文件与音乐缓存文件做旧版本Context兼容性补齐后合并返回。写操作则统一走合并 →split_cache_contexts拆分 → 分别async_save_cache的模式保证影视与音乐缓存互不污染。测试验证仓库中 tests/test_torrent_cache_music.py 覆盖了核心行为例如音乐条目在torrent.cache.get中返回正确的music_typereidentify_cache在显式指定music_typealbum时将album命名空间正确转发给识别调用断言recognize_kwargs[music_type] MUSIC_ENTITY_ALBUM自动重识别时保留音乐元信息与实体类型。这些测试可直接作为理解该 API 行为的可执行文档。Body Models 参考Torrent 类别自包含模型该类别文档是自包含的以下共享模型已内联Agent 无需加载第二个 Skill 文档即可构造调用。字段以*标记必填括号内为类型与默认值。ClassificationFacts分类事实自动分类策略评估后的规范化媒体事实。字段类型说明extensionsobject扩展提供的额外规范化分类事实field_sourcesobject规范化分类事实的来源出处identity*ClassificationIdentityFacts稳定的源端原生媒体身份media*ClassificationMediaFacts用于分类预览的媒体元数据输入musicClassificationMusicFacts|null音乐专属规范化事实ClassificationFactsPreviewInput分类预览输入facts*ClassificationFacts预览评估所用的规范化媒体事实。kindstringfacts默认facts请求选择的分类规则或预览输入类型。ClassificationIdentityFacts分类身份事实media_id*string源端原生媒体 ID与搜索返回的media_source精确配对。media_source*string元数据源标识保留与media_id一同返回的精确值。ClassificationMediaFacts媒体事实adultboolean|null是否标记为成人内容。companiesarray |null制作公司或工作室。content_ratingstring|null内容分级。countriesarray |null规范化国家/地区代码。genre_keysarray |nullMoviePilot 规范化类型键。genre_namesarray |null源端提供的类型名。languagestring|null规范化语言代码。networksarray |null电视网或流媒体平台。runtimeinteger|null持久化的工作流运行时元数据用于安全恢复。titlestring|null操作使用的媒体/种子/订阅/历史标题。type*string所选操作要求的 MoviePilot 媒体或存储条目类型。yearinteger|null用于消除歧义的发行年份。ClassificationMediaPreviewInput媒体分类预览输入kindstringmedia默认media分类规则或预览输入类型。media*object用于分类预览的媒体元数据输入。ClassificationMusicFacts音乐事实album_typestring|null音乐专辑或发行组类型。artist_countrystring|null艺术家所在国家/地区。artistsarray |null音乐艺术家名。entity_typestring|null音乐实体类型。genresarray |null规范化音乐流派值。release_statusstring|null音乐发行状态。secondary_typesarray |null次级发行组类型。tagsarray |null逗号分隔的豆瓣音乐分类标签仅配合豆瓣音乐探索源使用。ClassificationPolicy-Input分类策略categoriesarray 策略中完整的有序媒体分类定义。enrichment_modestring(primary_only,enrich_missing)默认primary_only填充分类事实的元数据增强模式。fallbacksobject无规则匹配时的回退分类或标签动作。field_aliasesobject源专属字段到规范化字段的可选别名映射。modestringfirst_match默认first_match操作模式。revisioninteger默认0最小0.0已发布策略修订号。rulesarray 按优先级从高到低求值的有序规则。schema_versioninteger2默认2服务端期望的策略 schema 版本。updated_atstring|null对象或执行状态最后更新时间。FileItem-Input存储条目basenamestring|null、childrenarray|null、drive_idstring|null、extensionstring|null、fileidstring|null、modify_timenumber|null、namestring|null、parent_fileidstring|null、pathstring|null默认/、pickcodestring|null115 网盘 pickcode、sizeinteger|null字节、storagestring|null默认local、thumbnailstring|null、typestring|null、urlstring|null。JsonData-Input任意 JSON 兼容辅助数据无直接可写字段。MediaSource/MediaType规范元数据源标识与源端原生 ID 配对与 MoviePilot 媒体类型均为运行时模型无直接可写字段。SubscriptionExecutionStatus订阅执行状态batch_idstring|null稳定的订阅搜索批次 ID。can_cancelboolean默认False当前执行是否可取消。current_site_idinteger|null当前处理的站点 ID。errorstring|null可读的错误信息。next_run_atstring|null下次计划搜索时间。phase*string订阅执行的当前阶段。sourcestring|null所选元数据或推荐源。state*string当前状态过滤。task_idstring|null稳定的持久化传输任务 ID。updated_at*string最后更新时间。TorrentInfo种子信息MoviePilot 搜索返回的单条种子候选核心字段包括category分类、date_elapsed发布时间可读表示、description、downloadvolumefactor/uploadvolumefactor站点下载/上传倍率、enclosure下载地址、freedate/freedate_diff免费期及剩余秒数、grabs完成下载数默认0、hit_and_run是否考核 HR默认False、labels、media_id/media_source成对身份、page_url、peers默认0、pri_order索引器优先级默认0、pubdate、seeders做种数默认0、site/site_cookie站点 ID 与 cookiecookie 视为机密、site_downloader、site_name、site_order默认0、site_proxy默认False、site_ua、size默认0.0、title、volume_factor综合体积倍率标签。WorkflowExecutionConfigmax_workersinteger|null工作流最大并发动作数。WorkflowExecutionState-Input/WorkflowRuntimeState持久化可恢复工作流执行状态errors/nodes/outputs/runtime/version默认1以及运行时进度状态attempts、finished_actions默认0、node_states、progress默认0、running_tasks默认0等。实战注意事项写操作需确认refresh、reidentify、delete、clear均有副作用Agent 在确认前不得执行delete/clear属于不可恢复操作。重识别失败前置条件显式提供媒体身份时media_source与media_id缺一不可音乐重识别只能使用音乐元数据源music_type仅接受recording/albumartist 仅可浏览。hash 复用torrent.cache.get返回的hash可直接用于delete/reidentify的路径参数无需自行重算如需自行计算算法为md5(title description)。刷新后校验执行refresh后用get回读确认缓存规模与媒体识别质量识别不准确的条目可针对性reidentify。缓存与站点解耦清空/删除缓存不会影响站点资源本身重建缓存依赖后续刷新动作若需强制全量重建可先clear再refresh。延伸阅读完整契约文档skills/moviepilot-api/api/torrent.md调用入口与路由规则skills/moviepilot-api/SKILL.md网关路由与策略登记app/agent/policy/api.py端点实现app/api/endpoints/torrent.py重识别用例服务app/application/torrent/cache.py缓存读取/拆分/刷新链app/chain/torrents.py测试用例tests/test_torrent_cache_music.pyAPI 表面审计清单docs/refactor/agent-api-surface-audit.md赞分享后端AI AgentMCP 服务AI 技能【免费下载链接】MoviePilotNAS媒体库自动化管理工具项目地址https://gitcode.com/gh_mirrors/mo/MoviePilot点击查看免费下载相关推荐深度解析POCO数据库查询缓存失效更新与删除操作的影响与优化深度解析POCO数据库查询缓存失效更新与删除操作的影响与优化 在构建高性能C应用程序时 数据库查询缓存 是提升性能的关键技术。POCO C Libr后端网络/通信数据库密码学Web框架Transmission种子完成后种子清理自动删除torrent文件Transmission种子完成后种子清理自动删除torrent文件 你是否遇到过下载完成后Transmission仍然保留着大量种子文件占用空间的问题是桌面应用后端CLI网络AutoGPT 平台 Airtable Records 记录操作块完整指南创建、查询、更新与删除AutoGPT 平台 Airtable Records 记录操作块完整指南创建、查询、更新与删除 本篇技术指南以 AutoGPT Platform 官方文档人工智能AI Agent自主智能体Agent 工作流工作流自动化后端前端上一篇探索 GreptimeDB一款强大的时间序列数据库下一篇鸟鸣Hummingbird微软开源的轻量级推理引擎创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考