diff --git a/README.md b/README.md index c27405307..e9507d571 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,7 @@ curl -fsSL https://raw.githubusercontent.com/jxxghp/MoviePilot/v3/scripts/bootst - 文档规则入口：[docs/rules/README.md](docs/rules/README.md) - 开发环境与本地源码运行：[docs/development-setup.md](docs/development-setup.md) - 测试说明：[docs/testing.md](docs/testing.md) +- 站点 API 接入需求：[docs/site-api-integration.md](docs/site-api-integration.md)，面向站点开发者，包含接口能力、认证、字段与联调验收要求。 - 新站点适配采集与 Feature Request 提交：[MoviePilot-Site-Collector](https://github.com/jxxghp/MoviePilot-Site-Collector/blob/main/docs/site-adapter-capture.md) - 站点采集器下载：[独立 Release](https://github.com/jxxghp/MoviePilot-Site-Collector/releases/latest)，仅在采集器变化时递增版本并发布。 - REST API 文档：https://api.movie-pilot.org diff --git a/README_EN.md b/README_EN.md index 1f896b89b..7f01d00a9 100644 --- a/README_EN.md +++ b/README_EN.md @@ -59,6 +59,7 @@ Before contributing, read the repository rules and local environment guide, keep - Rule index: [docs/rules/README.md](docs/rules/README.md) - Development setup and local source run: [docs/development-setup.md](docs/development-setup.md) - Testing guide: [docs/testing.md](docs/testing.md) +- Site API integration requirements (Chinese): [docs/site-api-integration.md](docs/site-api-integration.md), covering API capabilities, authentication, fields, and integration acceptance criteria for site developers. - New site adapter capture and Feature Request submission: [MoviePilot-Site-Collector](https://github.com/jxxghp/MoviePilot-Site-Collector/blob/main/docs/site-adapter-capture.md) - Site collector downloads: [independent repository Release](https://github.com/jxxghp/MoviePilot-Site-Collector/releases/latest), published only when collector inputs change. - REST API documentation: https://api.movie-pilot.org diff --git a/docs/site-api-integration.md b/docs/site-api-integration.md new file mode 100644 index 000000000..1835d8efc --- /dev/null +++ b/docs/site-api-integration.md @@ -0,0 +1,419 @@ +# MoviePilot 站点 API 接入需求 + +适用对象：PT 站点开发者及接口维护者 + +适用范围：通过站点官方 API 接入 MoviePilot（以下简称 MP） + +版本：1.0 + +日期：2026 年 11 月 4 日 + +本文说明站点需要提供哪些接口，才能支持 MP 的资源搜索、自动订阅、种子下载和用户数据展示。建议先打通“用户授权 → 搜索资源 → 获取种子文件”这一最小闭环，再补齐最新资源列表和用户数据。 + +**本文中的 URL、字段名、权限名称和 JSON 结构均为建议示例，不是 MP 已发布的统一站点 API 标准。** 站点可以沿用自己的接口，只要提供等价能力和完整文档，MP 侧再编写适配。已有接口满足需求时，无须专门复制一套接口。 + +## 1 接入能力与优先级 + +| 能力 | 优先级 | 用途 | 可以如何提供 | +| --- | --- | --- | --- | +| 适合后台长期使用的用户授权 | 基础必需 | MP 代表用户访问本人有权限的数据 | 个人 API Key、长期 Token，或可自动续期的授权机制 | +| 资源搜索和分页 | 搜索必需 | 手动搜索、订阅补搜 | 关键词搜索接口 | +| 获取种子文件 | 下载必需 | 将选中资源交给下载器 | 直接返回 `.torrent`，或先生成下载链接 | +| 最新资源列表和分页 | 完整自动订阅所需 | 周期获取新发布资源 | 独立列表接口，或搜索接口支持空关键词与发布时间排序；也可提供可用 RSS | +| 当前用户信息和统计 | 用户数据展示所需 | 展示账号等级、上传下载量、做种等 | 一个汇总接口，或拆分为多个接口 | +| 种子详情 | 按需必需 | 补齐搜索结果缺少的字段 | 搜索已返回全部所需字段时可省略 | +| 分类字典 | 推荐 | 将站点分类映射到电影、电视剧等 | 字典接口，或稳定的分类文档 | +| 未读消息、签到、收藏等 | 可选 | 扩展功能 | 按站点实际支持情况提供 | + +最小接入不要求提供签到、消息、收藏、发种、账户管理等功能。用户统计不影响基础搜索和下载；缺少这些接口时，相关展示能力无法完整提供。 + +## 2 认证与授权 + +### 2.1 推荐采用个人 API Key 或 Token + +建议用户在站点个人中心完成一次人工登录后，自行生成专门用于 MP 的访问凭据，并填入自己的 MP 实例。API 可以采用以下任一种鉴权方式： + +```http +Authorization: Bearer +``` + +或： + +```http +X-API-Key: +``` + +凭据应绑定具体用户，继承该用户的访问权限和下载限制。建议支持命名、查看使用时间、单独撤销和重新生成。用户主动撤销、账号被禁用或权限被取消后，接口应及时拒绝访问。 + +这里的“长期使用”不要求 Token 永不过期；关键是 MP 能在无人值守时持续工作。如果采用短期 Access Token，需要提供明确的刷新机制，并说明 Refresh Token 的有效期、轮换规则、并发刷新行为和失效后的重新授权方式。 + +### 2.2 建议权限范围 + +| 示例权限 | 允许的操作 | 需要该权限的能力 | +| --- | --- | --- | +| `torrent:read` | 搜索、列表、读取种子详情 | 搜索和订阅 | +| `torrent:download` | 获取种子文件或生成下载链接 | 下载 | +| `user:read` | 读取本人账号信息和统计 | 用户数据展示 | +| `message:read` | 读取本人未读消息 | 可选 | +| `checkin:write` | 执行本人签到 | 可选 | + +权限名称可以不同，也可以沿用站点既有权限模型。基础接入只需要资源读取和种子下载权限，不需要管理员权限。 + +### 2.3 请明确自动化访问条件 + +请说明以下事项： + +- API 凭据从哪里生成，哪些用户等级可以生成，是否需要额外开通权限。 +- 凭据是否过期，如何刷新或撤销，错误码分别是什么。 +- 是否绑定 IP、User-Agent 或设备；如果绑定，如何支持 NAS、Docker、代理和公网 IP 变化。 +- API 是否存在验证码、浏览器 JavaScript 挑战或必须交互的二次验证。建议用户授权时完成交互验证，正常 API 调用采用可独立校验的机器凭据。 +- 下载接口是否沿用同一 API 凭据，还是需要单独的下载凭据。 + +**能在网页中正常登录，或前端存在某个 Token 页面，并不能单独证明第三方客户端可以长期使用。需要确认实际账号可获得凭据，以及凭据可以访问哪些接口。** + +如采用 HMAC 或其他签名鉴权，请提供完整签名文档和不含真实密钥的测试向量，包括签名字符串组成、路径及查询参数规范化、请求体摘要、时间戳单位、允许时钟偏差、Nonce 规则、编码方式、签名算法及密钥获取方式。MP 应能依照公开协议计算签名，不应依赖复制网页内部临时状态。 + +## 3 资源搜索接口 + +### 3.1 建议请求 + +```http +GET /api/v1/torrents?keyword=Example&page=1&page_size=50&sort=published_at&order=desc +Authorization: Bearer +Accept: application/json +``` + +也可以采用 `POST` 并传 JSON。HTTP 方法和路径可以不同，请保持参数含义明确。 + +| 参数 | 要求 | 说明 | +| --- | --- | --- | +| `keyword` | 必需能力 | 支持中文和英文标题；说明多关键词按 AND、OR 还是整句匹配，以及搜索标题、副标题的范围 | +| `page` / `cursor` | 必需能力 | 页码或游标均可；明确页码从 0 还是 1 开始 | +| `page_size` / `limit` | 必需能力 | 明确默认值、最大值及实际返回数量 | +| `category` | 推荐 | 支持分类筛选；说明是否允许多个分类 | +| `sort`、`order` | 推荐 | 至少说明默认排序；最新列表需要可靠的发布时间降序 | +| `imdb_id`、`tmdb_id` 等 | 可选 | 按媒体 ID 精确搜索；说明电影与剧集 ID 的区分 | +| `free_only` 等促销筛选 | 可选 | 返回当前用户实际可用的促销资源 | + +至少提供一种可靠的分页结束标识，例如 `has_more`、`next_cursor` 或 `total`。如果接口存在最多可翻页数、最多返回条数或历史搜索窗口，也请明确说明。 + +### 3.2 种子记录字段 + +以下“必需”是指完成稳定搜索与下载所需的信息，字段可以由搜索或必要的详情请求提供。为降低请求量，建议搜索和列表直接返回常用字段。 + +| 建议字段 | 要求 | 类型与含义 | +| --- | --- | --- | +| `id` | 必需 | 站点内稳定、唯一的种子 ID，建议字符串；用于去重、详情及下载 | +| `title` | 必需 | 原始发布标题，保留年份、季集、分辨率、来源、编码、发布组等信息 | +| `size` | 必需 | 内容总大小，以字节为单位的整数，不是 `.torrent` 文件大小 | +| `download_url` 或按 ID 下载规则 | 必需 | 二者至少提供一种；短时链接的生成方式见第 5 节 | +| `subtitle` / `description` | 推荐 | 副标题、中文名或补充说明；尽量提供纯文本 | +| `details_url` | 推荐 | 用户在浏览器中打开的种子详情页地址；也可以提供可拼接规则 | +| `published_at` | 推荐；最新列表需要 | 原始发布时间，明确时区；不要用置顶时间替代 | +| `seeders` | 强烈推荐 | 当前做种人数，非负整数，用于判断资源可用性 | +| `leechers` | 推荐 | 当前下载人数，非负整数 | +| `completed` / `grabs` | 推荐 | 累计完成次数，说明统计口径 | +| `category` | 推荐 | 稳定分类 ID 或名称，并提供分类映射 | +| `download_factor` | 有促销时需要 | 下载计费倍率，例如免费为 `0`，半价为 `0.5`，正常为 `1` | +| `upload_factor` | 有促销时需要 | 上传计费倍率，例如正常为 `1`，双倍上传为 `2` | +| `promotion_end_at` | 限时促销时推荐 | 当前有效促销的截止时间，长期有效或未知时按文档约定处理 | +| `hit_and_run` | 有 H&R 规则时推荐 | 是否受下载后保种规则约束；最好同时说明规则 | +| `labels` | 推荐 | 如中字、国语、官种、DIY、HDR、杜比视界等标签 | +| `imdb_id`、`tmdb_id`、`douban_id` | 可选但有帮助 | 辅助媒体识别；保留来源及完整 ID，不同来源不能混用 | +| `info_hash` | 可选 | 用于种子身份校验或去重；说明 v1/v2 类型 | + +请注意以下语义： + +- 标题需要保留发布信息。例如 `Example.Movie.2026.2160p.WEB-DL...` 比仅返回中文片名更有利于 MP 识别和筛选。 +- 免费是“下载流量不计费”，与双倍上传分别表达。只返回 `FREE`、`2X` 等字符串也可以，但必须提供完整枚举映射。 +- 促销数据最好由服务端合并全站活动、种子活动和用户权益后，返回对当前用户实际生效的倍率；否则请提供明确的优先级和计算规则。 +- 如果促销规则未知，应允许表达未知，不能把缺失值当成免费。长期有效与截止时间未知也应可区分。 +- 是否有权限下载、是否触发 H&R、是否免费是不同概念，不要复用同一个字段。 +- 媒体 ID 要注明来源。对于 TMDB，还需说明是电影还是电视剧；单个种子包含多部作品时，不应随意指定其中一部代表全部内容。 + +### 3.3 建议响应示例 + +```json +{ + "code": "OK", + "data": { + "items": [ + { + "id": "123456", + "title": "Example.Movie.2026.2160p.WEB-DL.H265-GROUP", + "subtitle": "示例电影 / 国语 / 中英字幕", + "details_url": "https://tracker.example/torrents/123456", + "size": 21474836480, + "published_at": "2026-11-04T08:00:00+08:00", + "seeders": 50, + "leechers": 3, + "completed": 120, + "category": "movie", + "download_factor": 0, + "upload_factor": 2, + "promotion_end_at": "2026-11-05T08:00:00+08:00", + "hit_and_run": false, + "labels": ["国语", "中字"] + } + ], + "page": 1, + "page_size": 50, + "has_more": false + } +} +``` + +该示例采用“按种子 ID 调用下载接口”的方式，因此没有在搜索结果中返回下载链接。`code` 的类型和成功值可沿用站点规范；请提供全部业务错误码。 + +## 4 最新资源列表与自动订阅 + +为了支持 MP 周期性发现新发布资源，需要提供一种可靠的最新资源获取方式。 + +优先复用搜索接口：允许不传关键词，并按发布时间降序返回资源。 + +```http +GET /api/v1/torrents?page=1&page_size=50&sort=published_at&order=desc +``` + +也可以提供独立接口： + +```http +GET /api/v1/torrents/latest?page=1&page_size=50 +``` + +要求如下： + +- 返回字段尽量与搜索结果一致，避免为每个新资源额外请求详情。 +- 说明置顶、推荐、重复发布、编辑和删除资源的处理方式。 +- 排序应稳定。相同发布时间可用种子 ID 作为第二排序键；更推荐使用稳定游标。 +- 说明列表能回溯多长时间、最大条数，以及高发布量时如何翻页，避免轮询期间漏过新资源。 +- 如支持 `since`、`after_id` 或增量游标，请说明边界是否包含、游标有效期，以及它表示发布时间还是更新时间。 + +RSS 可以作为替代入口，但需要实际可用的用户授权方式、稳定资源标识和可下载的 enclosure，并说明条数与更新时间。JSON 列表接口和 RSS 的具体使用方式，需要 MP 侧适配，不是新增接口后就自动启用。 + +如果暂时只能提供关键词搜索，仍可先支持手动搜索及部分订阅补搜；但不能据此认为最新资源轮询能力已经完整。 + +## 5 种子下载接口 + +以下两种方式任选一种即可。**搜索返回一个种子 ID，并提供可按 ID 获取文件的接口，就能满足下载闭环，不要求搜索结果必须带永久下载 URL。** + +### 5.1 方式一 直接返回种子文件 + +```http +GET /api/v1/torrents/123456/download +Authorization: Bearer +``` + +成功响应示例： + +```http +HTTP/1.1 200 OK +Content-Type: application/x-bittorrent +Content-Disposition: attachment; filename="123456.torrent" + + +``` + +要求返回真实、完整、可解析的 `.torrent` 文件。私有站点的种子应包含适用于当前用户的 Tracker 认证信息，能被其下载器正常使用。 + +### 5.2 方式二 先获取短时下载地址 + +```http +POST /api/v1/torrents/123456/download-link +Authorization: Bearer +Accept: application/json +``` + +```json +{ + "code": "OK", + "data": { + "url": "https://download.example/torrent/123456?ticket=EXAMPLE_ONLY", + "expires_at": "2026-11-04T08:05:00+08:00" + } +} +``` + +随后由 MP 访问该 URL，取得实际种子文件。链接可以是签名 URL，不要求永久有效；建议在用户真正执行下载时才生成。 + +请明确： + +- 换取链接使用 GET 还是 POST，参数放在何处，JSON 中哪个字段是实际地址。 +- 链接有效期、是否单次有效，以及超时或网络失败后是否允许重试。 +- 下载地址是否仍需 Header、Cookie、Referer 或特殊 User-Agent；建议签名 URL 本身即可完成授权。 +- 是否有 IP 绑定，以及生成链接和下载文件是否必须来自同一出口 IP。 +- 是否重定向到其他域名，目标域名和鉴权规则是什么。 +- 重复获取文件是否消耗配额、重复登记下载，或产生其他业务副作用。 +- 用户无下载权限、等级不足、账号受限、种子被删除、票据过期等场景分别返回什么错误。 + +**不要在下载失败时返回 HTTP 200 的登录页、验证码页或错误 HTML。** 如果采用 JSON 错误响应，应以内容类型和状态码清晰区分种子文件与错误信息。 + +仅提供网页详情地址不能完成下载闭环。仅提供不含用户 Tracker 认证信息的磁力链接，对私有站点通常也不足以替代可用的个性化种子文件。 + +## 6 当前用户信息与统计 + +如希望在 MP 中展示完整站点账号数据，建议提供一个当前用户汇总接口： + +```http +GET /api/v1/me +Authorization: Bearer +``` + +| 建议字段 | 用途及口径 | +| --- | --- | +| `id`、`username` | 用户唯一标识、显示名称 | +| `level` | 用户等级名称，或提供等级 ID 到名称的映射 | +| `joined_at` | 注册时间，注明时区 | +| `uploaded` | 累计计费上传量，单位字节 | +| `downloaded` | 累计计费下载量，单位字节 | +| `ratio` | 分享率；下载量为 0 时需约定 `null` 等表达方式，不使用非法 JSON 数值 `Infinity` | +| `bonus` | 魔力、积分等数值；多种积分需区分名称和单位 | +| `seeding_count` | 当前做种数量 | +| `seeding_size` | 当前做种内容总体积，单位字节 | +| `leeching_count` | 当前下载数量 | +| `unread_message_count` | 未读消息数量，可选 | +| `updated_at` | 数据生成或最近更新时间，便于判断统计延迟 | + +上传量、下载量请注明是原始流量还是计费流量，建议两者都有时分别返回。做种体积请说明同一种子在多个客户端做种时如何计数。 + +如果站点不能直接汇总做种体积，可以提供当前用户的做种列表，包含种子大小并支持分页，由 MP 适配后汇总；这会增加请求量，因此优先推荐直接返回汇总值。 + +这些信息可以拆成 `/me`、`/me/stats` 等多个接口。不需要允许 MP 查询任意用户的私人数据，也不要求开放用户管理接口。 + +## 7 分类字典与种子详情 + +### 7.1 分类字典 + +建议提供： + +```http +GET /api/v1/categories +``` + +每个分类至少包含稳定 ID、名称及大类归属，例如电影、电视剧、动漫、纪录片、音乐、综艺等。如果分类稳定且很少变动，提供完整的静态映射文档也可以，不强制增加接口。 + +### 7.2 种子详情 + +```http +GET /api/v1/torrents/123456 +``` + +详情接口用于补齐搜索或列表缺少的信息，例如副标题、促销、H&R、媒体 ID 或下载信息。搜索结果已经完整时，无须强制为每个资源调用详情。 + +如果搜索结果属于“资源合集”，而不是具体种子，请提供从合集展开到具体种子列表的方式。每个可下载种子需要独立 ID、标题、大小和下载能力。 + +## 8 可选扩展接口 + +以下能力可以后续增加，不应阻塞基础接入： + +- **站内消息**：未读数量、列表和详情；消息提供稳定 ID，方便去重。标记已读属于独立写操作，不能因读取消息而隐式触发，除非文档明确且双方认可。 +- **签到**：提供签到接口，明确已签到的返回值、每日时区及重复请求行为。 +- **收藏或订阅书签**：查询、添加和删除收藏；需要用户授予独立写权限。 +- **用户做种和下载列表**：用于更丰富的数据展示，提供分页和统计口径。 +- **字幕**：字幕列表、语言、格式和下载接口。 +- **站点公告或活动信息**：便于展示公告、全站促销和维护状态。 +- **能力查询**：返回 API 版本、支持功能及限制，方便客户端识别差异。 + +提供可选 API 并不意味着 MP 会自动获得对应功能；需要另行确认现有模块或插件的适配范围。 + +## 9 通用协议与运行约定 + +### 9.1 数据格式 + +- API 使用 HTTPS，JSON 文本使用 UTF-8。 +- 大小和流量统一使用字节，人数和次数使用非负整数；积分及倍率允许小数。 +- 时间推荐采用带时区的 ISO 8601；使用 Unix 时间戳时明确秒或毫秒。 +- ID 建议采用字符串，避免超大整数在不同语言中丢失精度。 +- 明确缺失字段、`null`、`0` 和空字符串的含义；未知数据不要伪装成确定的零值。 +- 保持响应结构和枚举稳定；新增字段应尽量向后兼容，破坏性变更应提前通知并保留过渡期。 + +### 9.2 错误响应 + +建议同时使用正确的 HTTP 状态码和可供程序判断的业务错误码。例如： + +```json +{ + "code": "TOKEN_EXPIRED", + "message": "API token has expired", + "request_id": "example-request-id" +} +``` + +| HTTP 状态 | 建议含义 | +| --- | --- | +| `400` | 参数无效 | +| `401` | 未认证、凭据无效或过期 | +| `403` | 已认证但无相应权限，或账号受限 | +| `404` | 资源不存在或已删除 | +| `429` | 请求过于频繁，建议返回 `Retry-After` | +| `5xx` | 服务端异常或维护 | + +如果站点已有不同状态码或统一业务码规范，可以沿用，但需要提供准确对照。搜索没有结果应成功返回空数组，不能与认证失败、限流或接口故障混为一谈。 + +### 9.3 请求频率和网络环境 + +请提供每个用户、Token、IP 的限流维度，统计窗口、允许请求数、并发数和下载频率限制。搜索、最新列表、用户统计和下载接口如果限制不同，请分别列出，并给出建议轮询周期。 + +MP 为用户自行部署的应用，请求通常由 NAS、Docker 或服务器发起。建议对正式机器 API 采用 Token 鉴权和明确限流策略，避免正常调用被交互式浏览器挑战拦截。IP 限制、地域限制和代理限制应提前说明。 + +基础接入为 MP 后端调用站点接口，通常不需要站点为 MP 前端单独开放 CORS，也不需要站点回调或主动连接用户的 MP 实例。 + +### 9.4 凭据与用户数据 + +API Token、下载票据和带 passkey 的 URL 都是敏感信息。文档和联调日志使用占位符或脱敏值；真实凭据不应写入公开 Issue、示例代码或公共仓库。接口按当前用户权限返回资源和个性化种子即可，无须共享管理员凭据或用户密码。 + +## 10 请站点提供的联调资料 + +1. **接口文档**：Base URL、HTTP 方法、参数、请求 Header、字段类型、单位、成功及错误示例；OpenAPI 文档更方便，但不是硬性要求。 +2. **授权说明**：凭据生成入口、可用账号等级、权限范围、有效期、刷新及撤销方法，以及普通用户能否实际生成凭据。 +3. **搜索说明**：关键词匹配规则、分类字典、排序、分页、最大返回条数及历史数据范围。 +4. **最新资源说明**：空关键词是否可用、列表排序、增量或 RSS 能力、建议轮询间隔。 +5. **下载说明**：直接文件还是临时 URL、所需鉴权、有效期、IP 绑定、重定向和重试约定。 +6. **业务枚举**：分类、促销倍率、用户等级、H&R、账号状态和下载权限的解释。 +7. **脱敏样例**：至少覆盖普通种子、免费种子、双倍上传、限时促销、H&R、无权限和空搜索结果。 +8. **测试安排**：由双方约定私密授权渠道或测试环境，不在公开文档中附带真实 Token、Cookie、密码或 passkey。 +9. **运行限制**：限流、并发、维护响应、版本变更通知方式和技术联系人。 + +## 11 分阶段联调与验收 + +### 第一阶段 搜索和下载 + +- 用户能够生成、配置并撤销 API 凭据。 +- MP 能完成中文、英文关键词搜索，并正确翻页和识别无结果。 +- 标题、大小、人数和分类映射正确；有促销时，免费和倍率判断正确。 +- MP 能按种子 ID 获取文件，或现场换取短时下载链接并取得文件。 +- 下载器能够接受该种子并正常连接 Tracker，用户身份和权限正确。 +- 凭据失效、权限不足、资源删除和限流时，MP 能收到可区分的错误。 + +### 第二阶段 自动订阅和用户数据 + +- 最新资源能按约定排序、分页或增量获取；覆盖高发布量和相同发布时间场景。 +- 轮询和分页过程中能识别重复资源，并验证是否存在遗漏。 +- 普通、免费、双倍上传、促销到期和 H&R 样例与站点页面一致。 +- 用户等级、上传下载量、魔力、做种数和做种体积与站点统计口径一致。 +- Token 生命周期、正常重试和限流退避能在无人值守条件下工作。 + +### 第三阶段 可选功能 + +按双方约定验收消息、签到、收藏、字幕等能力。 + +接口可以访问或返回 HTTP 200，仅代表连通性；实际接入完成还需要验证数据解析、用户权限、个性化种子下载和下载器使用结果。 + +## 12 MP 侧适配与责任分工 + +站点负责提供稳定、正式支持第三方客户端的 API、鉴权方式和协议文档。MP 侧负责将站点接口转换为内部搜索结果、下载请求和用户数据，并完成站点配置、索引及必要的专用适配。 + +MP 已有 API Key 搜索及临时下载地址的实现案例，但不会自动识别任意新站点的 JSON 格式。一般需要检查主后端的站点适配，以及站点资源生成和发布链路。适配工作量取决于接口结构、认证方式及字段完整程度。 + +建议对方先确认以下五项：**能否签发适合无人值守使用的用户凭据，能否分页搜索，能否按 ID 下载种子，能否获取最新资源，能否读取本人统计。** 前三项形成最小闭环，后两项完善自动订阅和站点数据展示。 + +## 附录 MP 当前实现参考 + +以下链接用于理解 MP 已有数据模型和适配方式，站点无须照搬内部字段或下载请求编码。 + +- [搜索结果模型 TorrentInfo](https://github.com/jxxghp/MoviePilot/blob/52203041f7be117ddb3ec0ce8fcb7862ade26bda/app/domain/context.py)：标题、大小、发布时间、人数、计费倍率、媒体身份等。 +- [站点配置与用户数据模型](https://github.com/jxxghp/MoviePilot/blob/52203041f7be117ddb3ec0ce8fcb7862ade26bda/app/schemas/site.py)：API Key、Token、站点请求限流及用户统计字段。 +- [Rousi API 适配示例](https://github.com/jxxghp/MoviePilot/blob/52203041f7be117ddb3ec0ce8fcb7862ade26bda/app/modules/indexer/spider/rousi.py)：个人 API Key 搜索、分页，以及在下载时请求接口取得短时链接。 +- [MTorrent 适配示例](https://github.com/jxxghp/MoviePilot/blob/52203041f7be117ddb3ec0ce8fcb7862ade26bda/app/modules/indexer/spider/mtorrent.py)：搜索结果转换与下载凭据生成。 + +实现参考核对日期为 2026 年 11 月 4 日。本文的接口路径、字段设计和验收建议是供双方协商的接入需求，不代表每个现有站点都已实现全部能力。