UHD_Media_Tool/packages/agent/skills/import-troubleshoot/SKILL.md

name, title, description, triggers, capabilities, sessions

name	title	description	triggers	capabilities	sessions
import-troubleshoot	入库 / 整理问题排查	查一部作品为什么没入库、整理为什么失败、为什么认错作品，给出卡在哪一步和怎么处理。用户问「为什么 X 没入库」「整理失败了」「认错片了」时用。	没入库|没有入库|入库失败|不在(媒体)?库|没进库 整理(失败|出错|错了|不了) 识别(错|不出)|认错|没识别|对不上作品 为什么.{0,20}(没|不|还没)	inventory.query download.list download.inspect task.inspect decision.list identity.resolve organize.plan organize.execute metadata.enrich	chat investigate child

适用意图

• 「为什么《沙丘 2》没入库」「昨天下的剧怎么还没进库」「整理失败了」「这个文件认成别的片了」。

步骤

1. 定位作品：inventory.query（写作品名）看收录版本是否已满足、有没有已入库文件。已满足就直接回答「已经入库」并写文件位置。
2. 找下载：download.list 按作品名查这部作品的下载任务。没有下载任务就说明「还没下载」，并说是没找到资源还是没提交（看订阅 / 收录版本状态）。
3. 看卡在哪：对相关的那个下载任务调用 download.inspect，按顺序判断：
   • 还在下载 / 无进展 → 汇报进度和最近进展时间；
   • 已完成待整理 / 整理中 → 看关联的核验入库任务（task.inspect 看错误）；
   • 入库失败 → 读整理记录和错误，一句话说原因；
   • 有「没识别出作品」的待处理事项 → decision.list 确认，说明要用户指定作品。
4. 身份问题：资源还没对上作品时可以用 identity.resolve 提出映射；TMDB 查不到的作品，网页搜索开启时用 metadata.enrich 出建议。
5. 需要重新整理时：organize.plan 生成计划（不动文件），再 organize.execute。

需要批准

• organize.execute（执行整理）、identity.resolve（身份映射）需要授权；没有授权时写一句「没做：重新整理，需要你批准」。
• organize.plan、查询类不需要批准。

汇报模板

《沙丘：第二部》还没入库：下载已完成（昨天 22:10），整理时目标目录「电影」不可访问，入库失败。检查媒体库目录挂载后，在下载页点「重新整理」。

《沙丘：第二部》还在下载，进度 63%，最近进展 5 分钟前；下完会自动整理入库。

• 第一句写结论（卡在哪一步），第二句写原因或进度，第三句写用户要做的事（如有）。

不要做

• 不要向用户要下载任务 ID、种子 hash 或任务 ID：先 download.list 再 download.inspect。
• 业务任务 ID 用 task.inspect，下载任务 ID 用 download.inspect，不要混用。
• 不要猜原因：记录里没有的写「原因未确认」。
• 不要把整理记录路径以外的内部字段（状态码、fingerprint、ID）写进汇报。