trakt

Trakt 媒体发现

使用此技能查看正在观看的内容、广受欢迎的内容以及备受期待的内容。这是一个只读发现入口，并非目录元数据服务。

设置和身份验证

在 Trakt OAuth applications 注册应用，并导出其 Client ID：

export TRAKT_CLIENT_ID="YOUR_TRAKT_CLIENT_ID"

每个请求都必须发送 trakt-api-key: <client id>，并同时发送必需的配套标头 trakt-api-version: 2，以及 JSON 内容类型和描述性 User-Agent。公开发现端点使用密钥标头，而非 Authorization: Bearer。OAuth bearer token 用于标记为需要 OAuth 的端点，或用户范围内的列表、历史记录、收藏、待看列表和修改操作；bearer token 不能替代密钥和版本标头。

基本命令

全部六个发现命令都支持同时使用 --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 结果交给另一个工具

1. 运行 trakt --json movie trending --limit 20。
2. 解包 .movie，并保留 .watchers 作为观看热度信号。
3. 将可用的 .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。如果标头存在，分页键的值为整数；如果标头不存在，对象则为空 {}，因此 jq 表达式（如 .pagination.page_count // 1）可以安全地回退。标头存在时，人类可读输出会追加一行 Page N of M；否则不会追加内容。为保持兼容性，API 默认使用第 1 页、每页 10 项；要实现可复现的自动化，请明确设置这两个值，并在到达 page_count 时停止，而不要假定短页就是最后一页。

已知注意事项

• 必须成对提供请求头： 发送 trakt-api-key 时未同时发送 trakt-api-version: 2（反之亦然），可能导致无效请求或身份验证失败。随附脚本会在每次实时请求中注入这两个请求头。
• 401 与 403： 401 通常表示需要 OAuth 或授权无效；403 表示应用密钥无效或未经批准。不要盲目重试这两种错误。
• 速率限制： 收到 429 时，请遵守 Retry-After 并检查 X-Ratelimit。使用有次数上限的重试；可通过退避策略重试临时的 502/503/504 响应。
• OAuth 刷新： 访问令牌有效期为 7 天，刷新令牌只能使用一次。刷新成功后，请替换存储的刷新令牌；遇到 invalid_grant 时必须重新授权。
• Trakt 不等同于 TMDb： Trakt ID 和发现页排名不是 TMDb 元数据。要获取演职员信息、图片、平台元数据和目录补充信息，请使用 tmdb 技能。
• 趋势数据结构： 在读取标题/ID 前，先读取 .movie 或 .show，同时保留 watchers。
• 分页按每次调用处理： 每次 CLI 调用只获取一页（--page）；应循环调用并读取 pagination.page_count，不要指望脚本自行跟进链接。

适用场景

当需要当前观看信号、广泛人气、期待度以及可用于媒体工作流的标识符时，请使用 Trakt。

不适用场景

请勿使用此 CLI 读取或更新个人历史记录、待看列表、收藏集或列表。它既未实现这些命令，也不支持 OAuth；提供令牌并不能启用这些功能。请说明此限制，并使用 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。
• 无需 Client ID 即可使用 --dry-run，且不会执行网络 I/O。
• 实时发现需要 TRAKT_CLIENT_ID；测试仅使用模拟数据。