Files
UHD_Media_Tool/docs/runbook/organize.md
T
root c465b533fd merge: fix/q-inline-handling
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cxwgnn2pbzQ7rXv3rq7fei

# Conflicts:
#	apps/server/src/modules/sources-identity/service/episode-resolution.ts
2026-10-06 17:09:59 +08:00

186 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 媒体整理(`/console/organize`)
原地入库为 v0.3.14 的待部署改动;当前生产 v0.3.13 的整理方式仍为复制/移动,独立就地刮削继续可用。
整理页分为「整理队列」与「整理记录」。队列显示等待、执行和等待继续的后台入库任务;记录显示复制/移动/原地入库的处理结果。文件管理的改名、删除、还原账本继续保存,通用记录接口仍可查询。
实现:
- 列表 / 统计 / 详情:`apps/server/src/modules/acquisition-organize/routes/organization.ts`(筛选 `recordFilters`,通配 `likePattern`);公开字段在 `services/organize.ts` 的 `loadRecordsPublic`。
- 删除:`apps/server/src/modules/file-manager/record-delete.ts`(复用文件管理删除 `deleteFiles`)。
- 契约:`packages/contracts/src/organization.ts`(`OrganizationListQuery`、`OrganizationStats*`、`OrganizationDelete*`),端点 `Api.organization.stats / remove`。
- 前端:`apps/web/app/routes/console/organize.tsx`、`organize.$id.tsx`,`components/organize/`(删除确认框、标题 / 季集小件),批量重新整理走共用整理弹窗的 `{ kind: "records" }` 来源。
## 统一整理弹窗(v0.3.13)
手动选目录、文件管理器、下载详情与历史重新整理打开同一个弹窗。单文件只处理该文件,目录递归展开视频,多选合并去重。媒体类型可自动、电影或剧集;作品可自动识别、搜索本地/TMDB,也可选定类型后输入 TMDB ID 定位。手动指定作品与季号作用于整个本次范围,混合批次中需单独纠正的作品另行选取;文件明细可核对和修正季集、排除文件,没有另一套批量勾选语义。
各入口匹配相同来源配置,唯一匹配自动带出方式和分类/目标,多个匹配在弹窗内选定;不使用来源配置时沿用全局默认并手动指定。下载详情优先按已有 qB 标签匹配覆盖当前路径的来源。历史原配置仍覆盖可用输入时优先采用;成功移动后的目标不再属于旧来源时显示当前匹配配置或手动选项。
本次可选择原地入库、复制或移动。复制/移动可调整目标媒体库或具体目录、命名、目标冲突及整理后刮削。刮削默认沿用全局配置,显式开关只影响本次;整理成功的文件再进入现有 NFO/图片任务,TMDB 和 Local 均适用。做种义务未满足时不提供移动,复制与原地登记不改变视频文件,服务端继续核对实际状态。
手动来源发现真正成功历史时显示数量及「跳过成功记录」,**默认关闭**,开启后仅本次跳过;失败/部分成功记录不算完整成功,最新失败也不会遮盖较早成功。目标已存在策略单独处理。从历史记录进入直接采用重新整理语义。修改识别或选项后旧预览失效,需重新生成。
确认预览后只提供「加入整理队列」。后台受理成功后弹窗自动关闭,可以继续操作,进度到队列查看,整理后的刮削任务也显示在队列,整理详情单独展示刮削结果;部分受理时已受理文件从本次范围移除,剩余文件可修改后再预览提交。队列复用现有后台调度,不要求浏览器停留到文件处理结束。记录、队列及弹窗明细均复用统一分页。
## 整理时指定剧集组
对照 MP 的整理 / 重新整理选剧集组(`TransferInfo.episode_group`、`ReorganizeDialog.vue`)。作品的季集结构(TMDB 默认季 / 某个剧集组,见 `identity.md`「剧集组」)是作品级设置;整理弹窗里本次涉及的本地剧集作品如果有剧集组可选,多一项「季集结构」:
- **缺省「跟随作品(当前:X)」**:请求不带 `episodeStructures`,冻结计划和以前一样(不记季集结构)。
- **临时选 TMDB 默认季或作品的其它剧集组**(列表同 `GET /media-entities/{id}/episode-groups`):只这次按所选结构换算季集、定季目录与命名,作品设置不变。选的就是作品当前结构时等同跟随作品。
- **勾「同时设为作品的季集结构」**(缺省不勾):预览不改作品;执行时等计划一致、Move 授权、做种义务这些执行前检查都通过后,才走作品级切换(`setEpisodeGroup`:单元按 TMDB 原季集原地迁移、全量重算、刷新元数据,写审计),检查失败时作品结构不变;切换后按新结构(此时就是作品结构)再算一遍,前后路径须与预览一致,再整理。同一作品多组只切一次。
请求:`POST /files/organize` 的 `episodeStructures: [{ mediaEntityId, groupId | null, applyToEntity? }]`(预览与执行同一请求体,进请求指纹)。组响应带 `episodeStructure { groupId, name, temporary, appliedToEntity? }`,预览头部显示「季集结构:制作季(仅本次)」。
**临时结构下的集数映射**(`episode-resolution.ts createStructureEpisodeMapper`):
1. 季表换成所选结构的季与集数;选剧集组时带每集播出日期与原季集对照(发布者按 TMDB 默认季编号的 `S01E14` 换到组内 `S02E02`)。
2. 作品的映射规则是按作品当前结构写的:先按作品季表 + 规则跑一遍,命中规则(含特别篇 / 花絮 / 忽略)就用规则结果,季集再经 TMDB 原季集换到所选结构(换不过去的按待确认排除);没命中规则时按所选结构的季表判定。
3. 资源的集数解析是按作品结构做的,临时结构下不沿用,只取发布时间;按所选结构判不出的文件照常排除为集数待确认,但不并进作品的「集数待确认」待处理。
4. 向导里人工填的季集按所选结构理解(决定命名)。
**资产覆盖落到哪个单元**:作品的集单元是按作品当前结构编号的,所以文件的季集(所选结构)逐集换回作品结构再登记覆盖:所选结构季集 → TMDB 原季集(剧集组按组内位置,默认季即自身)→ 作品结构(作品是默认季时原季集即单元季集;作品是剧集组时按单元上记的 `tmdbSeason / tmdbEpisode` 对照)。区间里每一集都要换得到、落在同一季且连续;换不回(比如作品的剧集组不含这一集,或单元还没记原季集)时文件照常按所选结构命名入库,只是不登记集覆盖。例:作品是默认季(S1 = 25 集),临时按「制作季」整理 `S01E14` → 命名 `S02E02`,覆盖挂作品的 S01E14 单元;勾「同时设为作品结构」→ 先切换(S01E14 单元原地变成 S02E02),命名 `S02E02`,覆盖挂迁移后的同一单元。
**排查**:冻结计划 `plan.episodeStructure { groupId, name, entityGroupId, temporary, appliedToEntity? }` 记这次用了哪套结构与当时作品的结构;临时结构下每个文件的 `facts.structureEpisodes` 是命名用的季集,`facts.season / episodes` 是换回作品结构后的单元季集(换不回时没有),`episodeResolution.evidence` 带 `structure:<groupId|default>`。
不做:切换结构后自动改名已整理的文件(仍用「重新整理」)、剧集组季的独立海报。测试:`apps/server/test/file-manager/organize-episode-structure.test.ts`、`apps/web/app/components/organize-wizard/model.test.ts`「季集结构」。
## 来源、分类与存量整理
设置 → 媒体库与目录中维护分类 YAML 和整理来源。新功能已于 2026-10-01 部署为 v0.3.9,迁移 `0059_organize_source_snapshot` 已执行,见 发布记录(已删除,见 git `ceb66f8`)。
- 一条来源配置选一个来源目录、一个媒体库目标目录、复制或移动方式。通过弹窗浏览已登记的目录选择,不需要填写宿主机任意路径。不同来源可以使用相同分类,规则只维护一次。
- 分类一级固定为 `movie` / `tv`。规则按顺序首次匹配;同一规则的字段同时满足,同字段逗号值为任一匹配,`!` 排除。`release_year` 支持年份或区间;原始 TMDB 详情的一级字段也可使用。
- 空条件是兜底,应放在最后。默认保留「欧美电影」「欧美剧集」承接所有未命中的习惯。TV 默认顺序为儿童剧集、动漫剧集、纪录片、综艺、华语剧集、亚洲剧集、欧美剧集。尚未取得 TMDB 详情不能冒充分类成功。
- 自动分类在目标目录下追加分类目录,再使用现有作品/季目录模板。固定分类直接以所选目标为分类目录,避免追加第二遍分类名称。预览显示完整目标路径。已有作品沿用路径绑定,保存新规则不会移动旧库。
- YAML 保存后用于后续计划,重启保留;语法或目录名不合法时拒绝保存,已有规则保留。
来源触发方式可以选手动、qB 标签或目录快照。qB 标签同时限定下载器实例和来源范围;只有完成的任务进入整理,去掉标签后停止接管,已有管理标签继续有效。
新增来源或更改来源路径时,先将当前视频文件记录为基线,**这些文件不会因此自动入库**。快照持久化在数据库,重启保留。后续新增或改变的文件,在连续两次扫描确认大小和修改时间稳定后再处理。已知 qB 任务由下载器接管流程负责,避免两种触发重复整理。下载器目录会查询当前全部 qB 任务,即使未打标签、尚无数据库任务行,也会等下载完成。下载器不可达或目录读取失败会记录错误并保留此前快照。
「整理存量」是可重复触发的一次性扫描:排除同一源文件事实已成功整理的文件及未完成下载,历史部分成功中的失败文件、同路径发生变化的文件仍可选,候选进入同一个整理弹窗,确认识别、操作和完整目标路径后执行。单次候选按识别上限分批;完成后再次触发可处理余下文件。这个操作不重建或清空基线。识别不确定时也可打开现有智能助手协助判断,再加入整理队列。
文件管理器选中文件或目录后点「整理」,会读取来源配置并按同根、目录边界和最长来源路径匹配所选全部项目。唯一匹配自动带入复制/移动方式、分类和目标策略;多个同等匹配让用户选择,也可不用配置手动指定。不同来源混合选择或没有匹配时使用共用整理弹窗的手动选项。媒体类型在预览时核对,配置目标可由本次明确的目标选择覆写。
实现复用既有识别、冻结计划、文件操作账本、整理记录与任务引擎;未增加软链接、硬链接或另一套 AI 执行流程。
## 手动下载、Local 元数据与一次性洗版(已部署 v0.3.10)
搜索、站点工作台和原站详情均可独立下载,不要求订阅。下载时默认正常入库,也可选择一次性洗版并勾选旧版本;只有一个旧版本时默认选中,多个由用户选择。媒体详情与下载窗口展示已有文件和规格。正常入库保留已有版本;不同版本路径由可编辑的命名模板决定,同名冲突仍需处理。
未识别资源确认后允许下载。整理时先匹配 TMDB,再由现有网络/Agent 元数据补全能力核对译名、原名和别名;能够找到正确条目时回到 TMDB,找不到且详情资料充分时使用 Local 身份。Local 共用现有分类、命名、复制/移动和 NFO/图片任务,并保留字段来源;信息不足或候选冲突保留待处理。Agent 搜寻依赖已配置的模型/搜索能力和现有每日补全预算;没有封面资料时不会虚构图片。Local 入库安排元数据文件写入,普通 TMDB 自动刮削保持原设置。
洗版在本次冻结计划中保存选中的旧文件。新文件核验登记成功后才清理所选旧版本,剧集只处理成功对应的季集与 Part;覆盖不完整的合并集保留。相同目标路径会先暂存旧文件,失败后恢复。旧版的私有字幕等随之清理,共享 NFO/图片、未选版本及下载缓存保留;按现有文件替换设置移入回收站或删除。
## 收尾核验与资产登记
- 目标路径已有位置时:本次是「替换」(向导 / 待处理选替换,或洗版选中的旧版本),或旧位置属于别的作品,退役旧位置(没有别的位置时旧资产退役)并新建资产,大小、校验、版本信息都是新文件的;否则沿用同一资产。沿用的位置之前被对账判为缺失 / 不可用时恢复可用,资产事实换成这次入库的文件。
- 文件级标题粗核:同一批视频(合集、混合包)里,文件名解析出的标题和作品标题 / 原名 / 别名明显不是同一部的(没有足够共同词;
剧集只看带 SxxEyy 的文件),排除为待确认 `title_mismatch`,不按本作品命名入库,记录部分完成并开待处理「有 N 个视频没有整理」,
Move 时下载任务保留。只在同一批里至少有一个文件对得上作品时才判断别的文件(全都对不上多半是作品名的另一种写法,交给资源级识别);
用户在向导里逐文件指定过的不核。
- ffprobe 判定「不是视频」(没有视频流,伪装或损坏)的文件:核验失败,已拷 / 搬进库的新文件和它的字幕等附属文件移入回收站(Move 时源已删,回收站里是唯一一份),附属文件结果记跳过 `main_failed`,开待处理「N 个文件不是视频,没有入库」。原地入库不动原文件;洗版替换照旧回滚旧文件。
- 跨卷 Move(复制 → 校验 → 删源)删源前一律全量 sha256 校验,不用抽样;复制与同卷移动仍按 `verifyHash`。
- 计划期判断「目标已存在且同尺寸是不是同一文件」的全量 sha256 按(路径、大小、修改时间、inode)缓存,向导预览 / 复核 / 执行不再各算一遍。
- 整理时补全元数据(`metadata.resolve_organize`,模型 + 网页搜索)带 3 分钟超时,上游挂住不会一直占着文件道。
- 季号:解析器对有集号没季号的文件推定第 1 季,服务端与域层用同一个值(`organize-season-inference.test.ts`)。
- 回收站清除先删文件再删行;清过期项时顺带删各库根 `.umt-trash/replaced-*` 里过期、没有回收站登记的目录。
关联迁移 `0060_manual_acquisition`,已于 2026-10-01 随 v0.3.10 发布执行。业务依据与验收见 [MP 对照 §5.6](../porting/moviepilot-v3-comparison.md#56-本轮实现与验收已部署-v0310)。
## 与 MP 的对照
MP 对照源:`MoviePilot-Frontend/src/views/reorganize/TransferHistoryView.vue`、`components/dialog/TransferHistoryDeleteDialog.vue`、`app/api/endpoints/history.py`、`app/db/models/transferhistory.py`。
| MP 功能 | 我们 | 说明 |
| --- | --- | --- |
| 海报 | 新增 | 作品海报(`media.posterPath`),没有时显示首字占位 |
| 标题 / 年份 / 季集 | 已有 | `作品 (年) S01E02`;未识别的显示「未识别 · 源文件名」 |
| 二级分类(华语电影等) | 已接入 | 分类规则在设置编辑 YAML;电影 / 剧集为母分类,综艺属于剧集 |
| 源路径 → 目标路径 | 新增 | 列表加「源 → 目标」列(只显示末两段,悬停看全路径);详情「整理前 / 整理后」已有 |
| 存储标签(本地 / SMB…) | 不做 | 只有本地存储,标签不提供信息 |
| 整理方式 复制 / 移动 | 已有 | 列表「方式」列;整理页聚焦复制/移动结果 |
| 软链接、Rclone 复制 / 移动 | 不做 | 整理服务不支持这几种方式 |
| 大小 | 新增 | 逐文件源大小之和(`sizeBytes`) |
| 状态 成功 / 失败 + 失败原因 | 已有,改 | 支持「部分成功」;执行中任务在队列查看;成功不加徽章;失败原因走 `reasons.ts` 一句话,原码进详情「技术信息」 |
| 时间 | 已有,改 | 相对时间,悬停看完整时间 |
| 来源 下载器 / 手动 / 自动 | 新增下载器 | 来源列加下载器名称;详情加「下载任务」一行,种子 hash 进「技术信息」 |
| 关键字搜索(标题、源、目标;`*` `?` 通配) | 已有,补 | 补通配、逐文件的源 / 目标路径、种子 hash |
| 搜「成功」「失败」切状态 | 不做 | 有状态筛选和计数按钮 |
| 状态筛选 | 已有 | |
| 类型筛选 | 新增 | 电影 / 剧集 / 未识别(`kind=movie\|series\|none`) |
| 时间筛选 | 新增 | 今天 / 最近 7 天 / 最近 30 天(`since`)。MP 没有,任务单要求 |
| 统计(总数 / 成功 / 失败) | 新增 | 列表上方一行计数,只列非零项,点一下按该状态筛选(`GET /organization-records/stats`) |
| 分页、每页条数 | 已有(不同) | 共享分页组件,10/20/50/100 条和翻页;游标按需加载,无总数时显示「已加载」 |
| 列排序 | 不做 | 按时间倒序;分组模式下按作品聚合 |
| 分组模式(按标题) | 新增 | 「按作品分组」,组头可折叠 |
| 筛选写进地址栏 | 新增 | 状态 / 类型 / 来源 / 时间 / 关键字 / 分组都在 URL,刷新不丢 |
| 单条:重新整理 | 已有,补 | 详情已有;列表行菜单新增。走共用弹窗(配置、展开预览、加入队列) |
| 单条:智能助手整理 | 已有(不同) | 「让智能体排查」:失败 / 部分成功的记录在行菜单和详情里 |
| 单条:删除(只删记录 / 连源文件 / 连媒体库文件 / 全部) | 新增 | 确认框里两个勾选项,先核对再执行,写清删几个文件、多大、哪些删不了、会不会被自动整理再处理 |
| 查看详情 | 已有 | 详情加海报、大小、下载任务、删除按钮 |
| 批量选择 / 全选 | 新增 | 「批量」进入选择模式,表头全选 |
| 批量删除 | 新增 | 同单条删除确认框;删不了的逐条列出,其余照删 |
| 批量重新整理 | 新增 | 选中记录的可用文件一起进整理弹窗(成功移动取目标,其他取源);同属一个作品时预选作品 |
| 清空整理记录 | 不做 | 整理记录同时是文件变更的追溯记录;清理按保留期由计划页负责 |
## 需要处理(2026-10-06,待处理中心取消)
整理侧的问题(下载完识别不到、目标已存在 / 路径冲突、文件被排除、非视频、整理卡住 / 失败)不再进待处理中心,在整理记录里就地处理。
`decision` 表保留为内部机制(去重、触发智能体、自动关闭),整理侧事项的 subject 都是整理记录。
**口径**(`attentionSql`,`services/organize-records.ts`;列表 `?attention=true`、统计 `attention`、`GET /attention` 的 `organize` 共用):
没被同一下载任务后来的整理记录取代,并且(有 subject 为这条记录的未关闭事项,或失败 / 部分完成且 `attention_cleared_at` 为空)。
**行内动作**(`PublicOrganizationRecord.attention`:`topic` + 精简事项 + `agentIdentify`):
| topic | 原因 | 动作 |
|---|---|---|
| `identity` | 没识别出作品(`organize_identity:*`) | 指定作品(本地 / TMDB,`/decisions/{id}/resolve` → 钩子重新整理)、候选、让智能体识别、重新整理、忽略 |
| `conflict` | 目标已存在 / 路径冲突(`organize_blocked:*`、`path_conflict`) | 事项选项:替换 / 保留两者 / 跳过;忽略 |
| `other` | 被排除、非视频、卡住、执行失败… | 重新整理(整理向导)、忽略 |
- 忽略:`POST /organization-records/{id}/dismiss-attention` 记 `attention_cleared_at`(迁移 0078),关联的未关闭事项一并 `dismissed`。
- 让智能体识别:`POST /organization-records/{id}/agent-identify`,见 agent.md「整理识别不到作品时叫智能体识别」;识别失败缺省会自动派一次。
- 旧链接 `/console/inbox?kind=` 按问题类型跳转(`routes/console/redirects.ts inboxRedirect`):整理类 → 整理记录「需要处理」,
下载类 → 下载面板,健康类 → 运行状态 `#attention`,集数待确认 → 订阅。
**铃铛与汇总**(`GET /attention`):铃铛只放等你批准的智能体操作(subject 为 agent_run 的审批 / 方案选择、计划审批、`browser.waiting:*`;
整理记录上的审批不进)与系统健康(`source_unreachable`、`downloader_offline`、`cache_volume_unknown`、`space_insufficient`、
`library_root_offline:*`,恢复后自动关闭即消失)。首页「要我处理」与运行状态「需要关注」放汇总计数,点进去到对应页面。
## 删除
`POST /organization-records/delete {ids[≤200], deleteSource, deleteTarget, dryRun}`,scope `organize.execute`。
- 文件一律移入回收站,走文件管理删除(`deleteFiles`,mode=trash,`retireAssets=true`):已入库文件同时从媒体库移除(位置 removed、资产 retired、满足的收录版本转需关注 + 待处理)。回收站里能还原。
- 源文件 = 该记录逐文件结果的 `source_path`(只认执行进程本地视图);媒体库文件 = 成功文件的 `target_path`(相对库根时按库根拼)。已经不在的文件跳过、不拦。
- 只有复制 / 移动 / 原地入库 / 硬链接记录有文件可删;改名、移入回收站、还原类记录只删记录本身。
- 一条记录的任一文件不能删(做种未满足或下载中 `download_active`、绑定目录 `needs_unbind`、不在登记目录 `outside_roots`、目录离线等),这条记录连同它的文件都不动;还在整理的记录(`running`)不删。其余照删。
- 文件移入回收站会写一条「移入回收站」整理记录(同文件管理删除),`trashRecordId` 返回它。
- 下载器里的任务不删(同文件管理删除原则)。
- 删文件只允许管理员(控制台会话 / DEV key);API Key 只能删记录,删文件 403,需先走 `/files/delete` 的一次性审批。
- `autoRetry`:下载已完成但没入库(`download_task.status=completed`、本工具管理、没从下载器删除)且删完没有别的整理记录的下载任务数。自动整理扫描(`index.ts` 的补漏)会在几分钟后重新整理它们——与 MP 删失败记录后重新整理一致;已入库(`imported`)的不会。
- 删除不写增量读取的墓碑(`/organization-records/changes` 不会出现被删的记录);文件变化通过「移入回收站」记录可见。审计 `files.organize_records_delete`。
## 已知缺口
- 删媒体库文件只删整理记录里的文件,目录里的 NFO、图片与空目录保留(MP 在没有剩余视频时会连目录删掉)。
- 分组只对已加载的记录生效(同 MP 分组模式)。
- 统计的「进行中」= 排队 + 执行中;点它时列表只筛执行中。
## 原地入库(v0.3.14 待部署)
文件管理器选择已登记媒体库目录中的视频或目录,进入整理弹窗,默认选择「原地入库 · 保留位置与名称」。识别作品、手动指定电影/剧集、TMDB 和季集的方式与复制/移动相同,生成预览后加入现有整理队列。
- 源与目标路径相同;不复制、不移动、不重命名,不清理媒体目录中的临时文件。配对字幕/音轨同步登记,文件名和内容保持原样。
- 登记视频资产、所在库根、实际相对路径、版本信息与季集覆盖,已有同作品资产不重复创建;不新建会改变以后整理目标的目录绑定。
- 原地模式不使用来源配置的搬运目标、命名模板或替换策略,弹窗隐藏这些选项;不支持借此洗版或替换已有文件。
- 开启「整理后刮削」时,仅针对本次成功登记的视频在原目录补写 NFO/图片,不递归刮削整个同目录或该作品的其它版本。只登记/只读库根可原地入库,刮削关闭。
- 文件必须位于已登记、启用的媒体库根;下载缓存仍使用复制/移动或独立「刮削」。希望将现有目录直接作为媒体库时,先在设置登记该目录,然后原地入库。
- 预览与入队复用原计划校验;执行时确认文件未变化,不把已经归属其它作品的文件悄悄改绑。结果标为「原地入库」,可从整理记录重新整理。
此功能代码已实现,当前生产仍为 v0.3.13;本会话不能访问 Docker 或测试 PostgreSQL,部署及真实数据库回归尚待补验,见发布记录。