Trakt 媒体发现
用途
该技能用于查看当前正在被观看的内容、广泛流行的内容以及受到期待的内容。它是一个只读的发现界面，不是目录元数据服务。
设置与认证
在 Trakt OAuth 应用处注册应用，并导出其 Client ID：
export TRAKT_CLIENT_ID="YOUR_TRAKT_CLIENT_ID"
每个请求都必须发送 trakt-api-key: <client id>，并同时携带必需的配套请求头 trakt-api-version: 2，以及 JSON 内容类型和描述性的 User-Agent。公开发现端点使用 key 请求头，而不是 Authorization: Bearer。OAuth bearer token 用于标记为 OAuth-required 的端点，或用于用户范围的列表、历史、收藏、watchlist 和变更操作；bearer token 不能替代 key/version 这一对请求头。
主要命令
全部六个发现命令都接受 --page N 与 --limit N；两者默认值分别为 1 和 10，并会被转发到 API 的查询字符串中。
Trending：最近 24 小时内被观看的内容
trakt movie trending --limit 20 trakt tv trending --limit 20 --page 2 --json
Trending 响应会把每个媒体对象包裹在 movie 或 show 中，并包含 watchers 计数。
Popular：广泛的流行度排名
trakt movie popular --limit 25 --json trakt tv popular --page 2 --limit 25
Popular 是基于评分百分比和评分数量的排名，不是个性化推荐。
Anticipated：即将到来的关注度
trakt movie anticipated --page 3 --limit 10 trakt tv anticipated --limit 10 --json
Anticipated 反映的是列表出现情况和即将到来的兴趣，并不等同于发行日历。
全局标志可以出现在资源之前或之后：--json、--dry-run、--quiet 和 --verbose。
管道配方
将 Trending 交给另一个工具
运行 trakt --json movie trending --limit 20。
解包 .movie，保留 .watchers 作为观看信号。
将可用的 .movie.ids.tmdb 或 .movie.ids.imdb 传给下游工具；不要假设缺失的 ID 可以被合成。
trakt --json movie trending --limit 20 | jq '.movies[] | {title: (.movie.title // .title), year: (.movie.year // null), watchers: (.watchers // null), ids: (.movie.ids // .ids)}'
比较发现信号
获取 trending、popular 和 anticipated 的对应页面（例如每个都取 --page 1），然后在合并前为每个数据集打上标签。Trending 是近期观看，popular 是广泛排名，anticipated 是即将到来的兴趣。
翻页直到 anticipated 信息流结束
循环 --page，从 JSON 输出中读取 pagination.page_count 以确定停止页，并在某页返回空项时提前中断：
for p in $(seq 1 "$(trakt --json movie anticipated --page 1 --limit 100 | jq -r '.pagination.page_count')"); do trakt --json movie anticipated --page "$p" --limit 100 | jq --arg p "$p" '{page: ($p|tonumber), pagination: .pagination, movies: [.movies[] | {title: (.movie.title // .title), year: (.movie.year // null)}]}' done
将每页输出保留为带标签的 NDJSON；之后再合并。遇到 429 时，等待 Retry-After 结束后再继续循环。
JSON 与分页
--json 会输出一个对象，其中包含 movies 或 shows 数组（trending 条目保留其包裹结构），以及一个 pagination 对象，其键与 API 的 X-Pagination-* 响应头对应：page、limit、page_count、item_count。当响应头存在时，分页键为整数；当响应头缺失时，该对象为空 {}，因此像 .pagination.page_count // 1 这样的 jq 表达式可以安全降级。当响应头存在时，人类可读输出会追加一行 Page N of M，否则保持静默。为兼容性，API 默认 page 为 1、limit 为 10；为可复现的自动化，应显式设置两者，并在 page_count 处停止，而不是假设短页就是结尾。
已知注意事项
请求头必须成对：只发送 trakt-api-key 而不发送 trakt-api-version: 2（或反之）可能导致 invalid-request/认证类失败。捆绑脚本会在每次实时请求时注入两者。
401 与 403：401 通常表示需要 OAuth 或授权无效；403 表示应用 key 无效或未获批准。不要盲目重试这两种情况。
速率限制：遇到 429 时，遵守 Retry-After 并检查 X-Ratelimit。使用有界重试；瞬时的 502/503/504 响应可以用退避方式重试。
OAuth 刷新：访问令牌有效期为七天，刷新令牌为一次性使用。成功刷新后替换已存储的刷新令牌；invalid_grant 需要重新授权。
Trakt 不是 TMDb：Trakt ID 和发现排名不是 TMDb 元数据。使用 tmdb 技能获取演职员、图片、提供商元数据和目录增强信息。
Trending 结构：在读取 title/ID 之前先读取 .movie 或 .show，同时保留 watchers。
分页按每次调用计算：一次 CLI 调用只获取一页（--page）；应循环调用并读取 pagination.page_count，而不是期望脚本自行跟随链接。
何时使用
使用 Trakt 获取当前观看信号、广泛流行度、即将到来的兴趣，以及可输入媒体工作流的标识符。
何时不使用
不要使用此 CLI 读取或更新个人历史、watchlist、收藏或列表。它既不实现这些命令，也不实现 OAuth；提供 token 也不会启用它们。应说明该限制，并使用 Trakt 网站或另行实现的、经过认证的客户端进行个人操作。不要编造 CLI 命令，也不要声称所请求的更新已成功。使用 tmdb 获取目录元数据、演职员、图片和提供商可用性。
参考文件
文件 | 主题
references/auth-and-request-contract.md | 必需请求头、OAuth 边界、错误和速率限制
references/discovery-endpoints.md | 端点语义、过滤器、响应结构和分页
references/recipes-and-operations.md | 管道、jq 规范化和操作处理
可用脚本与前置条件
scripts/trakt 是一个可执行的 Python CLI，仅使用标准库和 requests。
--dry-run 无需 Client ID 即可工作，且从不执行网络 I/O。
实时发现需要 TRAKT_CLIENT_ID；测试仅使用 mock。