organize-files

整理文件

所有 MoviePilot 业务操作都使用 moviepilot_api。已弃用的文件、识别、转移和历史工具不可用。

工作流

1. 确定范围。如果用户提供了路径，就使用该路径。如果用户指出了下载器任务，就使用 downloader-operation 及其固定的 scripts/mp-downloader.py 辅助脚本来发现实例并调用 tasks.list。如果用户只指定了一个已配置的根目录，就调用 storage.settings。使用 storage.list 检查选定目录。没有明确且范围有限的指定时，不要处理宽泛的共享根目录。
2. 将文件分类为电影、剧集、单首音乐、一张完整专辑、字幕／附属文件或无关内容。不要仅仅因为无关媒体位于同一目录，就将它们归为一组。
3. 使用代表性标题或路径调用 media.recognize。如果不确定，就调用 media.search；如果仍有多个完全匹配的候选项，就使用 ask_user_choice。绝不臆造或翻译 ID。
4. 保留准确的 media_source + media_id。对于剧集，如果编号有歧义，就使用 media.detail 核实季详情。对于音乐，单首录音是一首曲目，专辑是一个包含多首曲目的目录，艺人仅用于浏览。
5. 如果存在重复风险，就调用 library.exists。如果已有的转移记录会影响重新整理，就检查 transfer.history。
6. 在执行会改变状态的转移之前，总结来源、目标身份、媒体类型、季／音乐实体、存储位置和模式。只有当用户的请求已明确授权该具体操作，或用户确认后，才能继续。
7. 对每个已核实的单元调用一次 transfer.file。对于专辑，仅当其支持的音频文件数量与所选专辑详情一致时，才转移一次整个专辑目录。
8. 如果用户有此要求，就在转移成功后调用 media.scrape。报告实际的标签、封面和歌词数量；绝不要假定已找到所有歌词。

结构化调用

• 目录列表：在 body 中通过存储位置／路径／分页／排序调用 storage.list。
• 识别：在 query 中通过标题／路径调用 media.recognize。
• 搜索：在 query 中通过标题／类型／来源约束调用 media.search。
• 详情：通过 path_params.media_id 以及 query 中的身份／类型调用 media.detail。
• 媒体库检查：在 query 中通过准确的身份调用 library.exists。
• 转移：在 body 中附带手动转移请求，调用 transfer.file。
• 即使批次报告失败，实际转移响应也会包含 data.items。检查每项的 state：accepted 和 retry_wait 表示后台仍有任务；只有 completed 才确认执行并完成结算。manual_review 要求先在转移队列中处理该任务；failed 和 skipped 不代表已导入。不要重新提交已包含 accepted 或 completed 项的整个批次。预览响应仅包含规划数据，不包含执行状态。
• 抓取：在 body 中附带文件项，在 query 中附带准确的身份／类型字段，并通过 path_params.storage 调用 media.scrape。

如果源文件缺失、目录配置不存在、身份仍有歧义、专辑看起来混杂或不完整，或请求的目标会覆盖无关媒体，请停止并报告，不要转移。

整理恢复与历史上下文

保留 storage.list 返回的完整文件项，包括可选的 modify_time_ns 和 change_time_ns；不要自行生成本地版本凭据。恢复发现源或目标版本变化时， 应报告人工复核状态并保留现场，不通过重新提交整个批次绕过核验。 复用历史整理电视剧时保留 episode_group；不同剧集组分批处理。 目录整理的 overwrite_skipped 同样表示未导入，不能报告为成功。