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

## 适用意图

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

## 步骤

1. 定位作品：inventory.query（写作品名）看收录版本是否已满足、有没有已入库文件。已满足就直接回答「已经入库」并写文件位置。
2. 找下载：download.list 按作品名查这部作品的下载任务。没有下载任务就说明「还没下载」，并说是没找到资源还是没提交（看订阅 / 收录版本状态）。
3. 看卡在哪：对相关的那个下载任务调用 download.inspect，按顺序判断：
   - 还在下载 / 无进展 → 汇报进度和最近进展时间；
   - 已完成待整理 / 整理中 → 看关联的核验入库任务（task.inspect 看错误）；
   - 入库失败 → 读整理记录和错误，一句话说原因；
   - 整理记录「没识别出作品」→ decision.list 确认事项，按下面第 4 步认作品；认出来用 organize.assign_identity 指定（会重新整理），认不出说明要用户在整理记录里指定作品。
4. 身份问题：资源还没对上作品时可以用 identity.resolve 提出映射；TMDB 查不到的作品，网页搜索开启时用 metadata.enrich 出建议。整理要用的资源连常规识别也对不上作品时，用 metadata.resolve_organize 补全译名重查 TMDB，仍没有合适条目才建立带来源证据的本地作品。整理时「没识别出作品」的记录（接管任务、文件名认不出）：catalog.lookup / inventory.query 核对标题、年份、类型和季集都对得上后，organize.assign_identity 写一次（带依据），系统按该作品重新整理；拿不准不要指定。
5. 需要重新整理时：organize.plan 生成计划（不动文件），再 organize.execute。

## 需要批准

- organize.execute（执行整理）、identity.resolve（身份映射）需要授权；没有授权时写一句「没做：重新整理，需要你批准」。
- organize.plan、查询类不需要批准。
- organize.assign_identity（指定整理作品）不需要持续授权：用户对话里可直接用，后台识别会话只能处理它自己那条记录。

## 汇报模板

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

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

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

## 不要做

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