TMDb 技能用于在终端中查询电影与电视的 TMDb 元数据，定位为只读的信息发现工具。
用途与适用场景
该技能适合只读的电影与电视元数据发现，包括演职员、发行信息、分级、图片、推荐以及提供商元数据等。明确不适用于以下场景：种子或盗版搜索、播放或下载流媒体、维护个人已看/未看状态；观看历史类工作流应使用 trakt，可用性相关操作应使用播放或目录集成。
配置方式
需先在 TMDb API 设置中创建凭据，推荐使用 API Read Access Token：
export TMDB_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
或使用 v3 key： export TMDB_API_KEY="YOUR_API_KEY"
CLI 会发送 Authorization: Bearer $TMDB_ACCESS_TOKEN 或 ?api_key=$TMDB_API_KEY。两种形式具有相同的 v3 访问级别，只需配置其中一种。--help 和 --dry-run 不需要凭据。
常用命令
搜索与识别：
tmdb movie search --term "dune" --limit 5 --json tmdb tv search --term "severance" --limit 5 tmdb find tt0111161 --source imdb_id --json
--source 仅接受官方外部源值之一：imdb_id、facebook_id、instagram_id、tvdb_id、tiktok_id、twitter_id、wikidata_id 和 youtube_id。不支持 Freebase 查询：已退役的 freebase_mid 和 freebase_id 会被拒绝。响应会拆分为 movie_results、tv_results、person_results、tv_season_results 和 tv_episode_results。
详情与补充：
tmdb movie detail 550 --append credits,videos --json tmdb movie detail 550 --append 'credits,watch/providers,external_ids' --json
复合响应的顶层键使用所请求的名称。在构造原始 URL 时需对 watch/providers 中的斜杠进行编码。
发现与浏览：
tmdb movie discover --genre horror --rating 7 --limit 10 tmdb movie discover --genre horror --certification R --from 2024-01-01 --to 2024-12-31 tmdb trending --type all --window week --limit 20 --json tmdb genre list --type movie --json tmdb genre list --type tv --json tmdb certification --json
在原始 discover 请求中，应结合使用 vote_count.gte 与 vote_average.desc，以免票数极少的条目占主导。在当前的 TMDb 文档中，逗号分隔的类型 ID 为 AND，竖线分隔的 ID 为 OR。
管线示例
IMDb ID 转为已补充的影片信息：
curl -s -H "Authorization: Bearer $TMDB_ACCESS_TOKEN"
'https://api.themoviedb.org/3/find/tt0111161?external_source=imdb_id' > /tmp/find.json
id=$(jq -r '.movie_results[0].id' /tmp/find.json)
curl -s -H "Authorization: Bearer $TMDB_ACCESS_TOKEN"
"https://api.themoviedb.org/3/movie/$id?append_to_response=credits,videos,watch%2Fproviders"
| jq '{title, runtime, director: [.credits.crew[] | select(.job == "Director") | .name], cast: [.credits.cast[0:5][].name], providers: .["watch/providers"].results.US}'
先搜索后取详情：
tmdb movie search --term "dune" --limit 1 --json > /tmp/search.json id=$(jq -r '.results[0].id' /tmp/search.json) tmdb movie detail "$id" --append recommendations,similar --json
过滤可靠发现：直接使用 API 时，可组合日期窗口、竖线 OR 或逗号 AND 的类型表达式、vote_count.gte 以及 sort_by=vote_average.desc，然后用 jq 只保留下一步工作流所需字段。
JSON 与 jq：--json 可放在子命令之前或之后。JSON 搜索结果包含 results，通常还有分页字段 page、total_pages 和 total_results；服务将页码限制为 500。可使用 jq -r '.results[] | [.id, (.title // .name)] | @tsv' 生成稳定的表格交接。
已知注意事项
凭据二选一：api_key 与 Bearer 是替代关系，不能混用。凭据被拒通常产生 HTTP 401、status_code: 7 和 Invalid API key: You must be granted a valid key。权限失败使用代码 3。代码 33 表示请求令牌无效，而非此 API-key 信息。
分页上限：页码从 1 开始，最大 500，超限请求会失败。搜索/发现访问实际上限约为 10,000 条结果，即使总数看起来更大。速率指引约为每秒 40 次请求，遇到 429 响应应遵守 Retry-After。
复合语法：append 值以逗号分隔，最多 20 次调用。watch/providers 含有斜杠，因此在 curl 中需进行 URL 编码，并使用 jq 的 ."watch/providers" 记法。
外部 ID 结构：/find/ 不返回单一通用 id；在选择电影或电视详情前需检查相应的嵌套数组。只有八个已记录的外部源值有效，已退役的 Freebase 源（freebase_mid、freebase_id）会被拒绝。
提供商筛选：with_watch_providers 需要 watch_region；提供商数据带有 JustWatch 署名要求。
本地化与图片：为保证可复现性，应使用 language=en-US 并指定市场区域。图片 URL 需由 /3/configuration 的 secure base URL、有效尺寸和返回的路径拼接而成。
参考文件
references/auth-pagination-and-errors.md：凭据、分页、速率限制、错误、语言、区域和图片。 references/find-and-details.md：IMDb/TVDB 查询、响应映射、详情字段、复合请求。 references/search-discover-trending.md：搜索、发现筛选、趋势、类型、分级和发行列表。
可用脚本与前置条件
scripts/tmdb 是一个可执行的 Python CLI，仅使用标准库和 requests；它保留 --json、--dry-run、--quiet 和 --verbose。 scripts/test_tmdb.py 是离线的 unittest/pytest 测试套件；所有 HTTP 行为均为 mock。 需要 Python 3.8 及以上和 requests。此技能不启动任何服务。