pt-plugins/pt-depiler/ptd-site-definition

PT-depiler 站点定义（site definition）编写

目标产物是 src/packages/site/definitions/<id>.ts：一个文件定义一个站点，导出 siteMetadata: ISiteMetadata，按需再导出一个覆写引擎行为的 default class。本 skill 只讲「如何写这个文件」；修改 types/ 公共类型或 schemas/ 引擎实现属于另一层次的工作，除非用户明确要求，不要顺手改动。

先理解加载机制（决定了哪些东西必须写、哪些不用写）

• src/packages/site/index.ts:21-29 用 import.meta.glob 自动收集 schemas/*.ts 与 definitions/*.ts。新增定义文件不需要注册到任何列表，文件名（去扩展名）就是 siteId。
• 实例构造顺序见 index.ts:79-102：

1. definition 导出了 default class → 直接用它；
2. 否则取 siteMetadata.schema 指向的 schema 类；
3. schema 值在 schemas/ 里没有对应实现 → 按 type 回落 AbstractPrivateSite（private）或 AbstractBittorrentSite（public）。

• index.ts:41-42：siteMetadata.schema 缺省时同样按 type 回落，所以不写 `schema` 也合法。
• `SchemaMetadata` 不会被自动合并：index.ts:100-101 从 schema 模块只取 default class。definition 必须自己写 ...SchemaMetadata 才能拿到引擎默认值（如 search/userInfo/detail），否则该站点的这些配置就是空的。
• index.ts:53-59：urls / legacyUrls / trackerUrls 会做 rot13 还原后再使用（只有这三个字段会还原，其它字段里写 uggcf:// 不会被解出来）。
• index.ts:59-60：tags 缺省为 []；timezoneOffset 缺省为 NexusPHP 站点 +0800、其余 +0000。

工作流

1. 判定引擎：先确定目标站点由哪个 schema 承载（NexusPHP / Unit3D / Gazelle / GazelleJSONAPI / AvistazNetwork / Luminance / Rartracker / TCG / 仅基类）。判定依据写在各个引擎文档的「判定站点是否属于该引擎」一节。
2. 读该引擎的 reference：见下方「按需读取」。不要凭记忆套模板，不同 schema 的 SchemaMetadata 默认值差异很大。
3. 收集事实：category 的 value→name、搜索入口、选择器、等级要求必须来自真实页面、接口响应或站点规则页。拿不到就明确写出假设并向用户确认，严禁为了让文件"看起来完整"而编造数值、选择器或接口路径。
4. 写文件：以同引擎既有定义文件为骨架（...SchemaMetadata 展开 + 覆写差异项），只写与默认值不同的部分。
5. 校验：跑 pnpm check（vue-tsc --noEmit + 站点定义的静态校验，见下），必要时跑 pnpm format。
6. 交付：说明改了什么、依据是什么、哪些值来自真实站点、哪些是待确认的假设。

硬性规则

• id = 文件名，必须匹配 /[0-9a-z]+/（无大写、无特殊字符，见 types/site.ts:36-44）。若 Jackett 有同名站点配置，优先与其命名一致。
• version：必填数字，既有定义全部显式声明（2026-09 的 master 上 301 个定义文件无一例外）。types/site.ts:46-54 的约定是「模板类 -1；NexusPHP / Unit3D / Gazelle / GazelleJSONAPI / AvistaZ 系 0 且无需递增；其余站点 >0」。

但仓库现状与文字约定不一致：引擎类定义普遍写 1（2026-09 统计：NexusPHP 164 个定义里 158 个写 1、Unit3D 35 个里 31 个、GazelleJSONAPI 14 个里 12 个），模板类站点也常写 1。 实际做法：跟随同引擎既有文件的取值（绝大多数是 1），同一站点内保持一致；修改既有站点时不要顺手改这个字段（除非该站点本来就用 YYYYMMDD 式自定义版本号）。

• urls：第一个是默认使用地址；支持 https 就优先 https；敏感站点网址可写成 rot13（uggc:// / uggcf://，类型见 types/base.ts:11-21，还原见 utils/html.ts:49）。
• 成人站点（`tags` 含 `成人` / `XXX` / `Adult`，大小写不敏感）的 `urls` / `legacyUrls` / `trackerUrls` 必须全部写成 rot13，由 vite/scripts/checkSiteDefinition.ts 强制（error）。配套约束：
• 这三个字段是唯一会被 restoreSecureLink 还原的地方，所以 favicon（不还原）、Origin/Referer 请求头、绝对的 search.requestConfig.url 等字段里也不得再出现本站域名的明文 —— 改成从 restoreSecureLink("uggcf://...") 派生的模块级常量、本地图标（./x.png），或者省略该字段（favicon 省略后会由 utils/favicon.ts 从首页自动解析）。校验器会按「明文地址的 host 是否命中本站已收录域名」来报错。
• 站点登录态/请求头需要明文域名时，范例见 definitions/pussytorrents.ts 的 SITE_ORIGIN。
• legacyUrls：更换域名时不要删 urls 里的旧地址，把它移入 legacyUrls；若该域名曾出现在 ptpp 中而未出现在 urls 中，必须补进 legacyUrls（types/site.ts:88-96）。
• favicon（types/site.ts:98-106）：可写完整 https://.../favicon.ico、./<name>.png（public/icons/site/ 下的文件）或 data:image/...；若 public/icons/site/ 已存在 {id}.{png,ico,svg} 则无需声明。
• isDead：只在站点彻底死亡、无恢复可能时写 isDead: true；临时不可用应交给用户配置，不要写进 metadata（types/site.ts:108-115）。
• prettier：printWidth 120、分号、trailing comma all（根 package.json 的 prettier 配置）。
• `userInfo.process[*]` 的字段声明按层分工（types/site.ts:355-363）：每步要取的字段是 [...fields, ...Object.keys(selectors)]，二选一即可，不要两处都写。
• schema（`schemas/*.ts`）优先用 `process[*].fields`：字段清单写在步骤里，具体选择器放在全局 userInfo.selectors；这样 definition 只需覆写选择器就能快速适配站点改版，不必重写请求流程（NexusPHP / Luminance / Gazelle 等引擎都是这个形态）。
• definition（`definitions/*.ts`）自己掌控 `process` 时优先用 `process[*].selectors`：选择器的键本身就说明了「这次请求要取哪些内容」，字段与选择器不会各写一份而对不上（范例：definitions/myanonamouse.ts、definitions/cgpeers.ts）。
• 若同时修改了公共类型/schema，必须同步检查其余定义文件是否受影响（definitions/ 下 300+ 个定义文件、10 个 schema）。

按需读取

静态校验

站点定义的结构与正则校验已内置进 pnpm check（实现：vite/scripts/checkSiteDefinition.ts），不需要单独跑脚本，也不在构建里跑：

pnpm check                                   # = vue-tsc --noEmit && 站点定义全量校验
pnpm check:site-definition                   # 只跑站点定义校验（全量）
pnpm check:site-definition src/packages/site/definitions/<id>.ts   # 只校验指定文件（会列出它的提示）

守卫检查：文件名与 id 是否一致、id 是否合法且不与其他定义重复、必填字段是否齐全、type 取值、urls 是否非空且可 rot13 还原、成人站点（`tags` 含 `成人`/`XXX`/`Adult`）的 `urls` / `legacyUrls` / `trackerUrls` 是否全部 rot13、以及文件里是否还有本站域名的其它明文地址、timezoneOffset 格式、category 的 key 是否重复、levelRequirements 的 id 是否重复或非递增、以及所有会被 `new RegExp(pattern, "i")` 编译的 pattern 字段（`urlPattern` / `excludeUrlPattern` / `urlPatterns` / `refreshHeaderPattern` / `officialGroupPattern`）里的字符串能否编译；并对 schema 命名、version 口径、明文 http 给出警告。

错误（error）会让命令以非 0 退出（`pnpm check` 随之失败）；警告与提示不影响退出码。 它只做静态结构检查，不能替代真机运行验证。

交付前检查清单

• [ ] id 与文件名一致，且只含小写字母与数字
• [ ] version 与同引擎既有文件取值一致（新增站点通常为 1）
• [ ] urls 至少一项，首个为默认地址，可用 https 就用 https；旧域名进了 legacyUrls
• [ ] 若 tags 含 成人 / XXX / Adult：urls / legacyUrls / trackerUrls 全部是 rot13，且文件里没有本站域名的其它明文地址（favicon / Origin / Referer / 绝对 URL 都要处理掉）
• [ ] type 与 schema 匹配；schema 若填的是 schemas/ 里没有的名字，则该文件必须导出 default class 承载它
• [ ] 展开了 ...SchemaMetadata（而不是手抄引擎默认值），只额外写与默认不同的部分
• [ ] category 的每个 key 在站点内唯一，value 与站点真实分类一致
• [ ] userInfo.process[*] 的字段声明符合分层约定：definition 侧用 selectors（键即字段清单），没有和 fields 重复声明；覆写引擎步骤时展开了 ...SchemaMetadata.userInfo!.process![n]
• [ ] 所有选择器/接口路径都有真实依据，没有猜测值
• [ ] pnpm check 通过（含站点定义的结构与 pattern 编译校验）
• [ ] 若覆写了类方法，确认签名与基类一致（override 关键字、参数个数与类型）