================================================================================ TVBox Desktop · 功能框架设计书 Windows 桌面影视聚合客户端 | 纯白极简 · 电脑宽屏 · 内容密集 ================================================================================ 文档版本 : v0.1 目标平台 : Windows 10 / 11 (x64) 技术形态 : Electron 桌面客户端 编写日期 : 首版框架设计 配套代码 : D:\tvbox ================================================================================ 0. 一句话定位 ================================================================================ 把安卓 TVBox 的「配置订阅 + 多站点聚合搜索 + 多线路选集播放」这套能力搬到 Windows 电脑上,界面走纯白极简路线,但利用电脑宽屏优势把内容密度做高: 一屏能看到足够多的海报、剧集和搜索结果,鼠标操作优先,键鼠快捷键齐备。 ================================================================================ 1. 技术选型 ================================================================================ 外壳 Electron 跨平台桌面外壳,Windows 免额外工具链 构建 electron-vite 主进程/预加载/渲染进程三端统一构建 界面 React 18 + TypeScript 组件化 + 类型安全 样式 原生 CSS + CSS 变量 不引入 UI 框架,纯白设计体系完全自控 状态 Zustand 轻量全局状态(配置源、站点、播放状态) 路由 react-router-dom HashRouter(桌面端避免 file:// 路由问题) 播放 ArtPlayer (MIT) 开源播放器内核,控制条可完全自定义 流媒体 hls.js (Apache-2.0) m3u8 / HLS 播放,兼容绝大多数采集站 HTML解析 cheerio 用于 type=1 的网页型站点兜底解析 编码 iconv-lite GBK/GB2312 直播源与网页转码 本地存储 JSON 文件 放程序同级的 data\ 目录(便携),避免原生模块重编译 打包 electron-builder NSIS 安装包 + 免安装 zip 设计原则 1) 主进程负责一切网络请求与文件读写,渲染进程只管展示(安全 + 可绕过 CORS) 2) 不引入需要 node-gyp 编译的原生依赖,保证 clone 下来就能跑 3) 所有对外协议尽量兼容 TVBox 既有生态,能直接吃现成订阅 ================================================================================ 2. 目录结构 ================================================================================ D:\tvbox ├─ package.json ├─ electron.vite.config.ts ├─ tsconfig.json / tsconfig.node.json / tsconfig.web.json ├─ 功能框架.txt ← 本文档 ├─ resources/ 应用图标等静态资源 └─ src/ ├─ shared/ 主进程与渲染进程共用的类型定义 │ ├─ types.ts Site / Vod / VodDetail / Parse / Live 等 │ └─ ipc.ts IPC 通道名常量 ├─ main/ 主进程(Node 环境) │ ├─ index.ts 窗口创建、生命周期、IPC 注册 │ ├─ window.ts 窗口配置(1440x900,白底,无闪白) │ └─ services/ │ ├─ store.ts JSON 文件读写(设置/收藏/历史) │ ├─ http.ts 统一请求:UA/Referer/超时/重试/Gzip │ ├─ config.ts 配置源拉取、解析、合并、缓存 │ ├─ sites.ts 站点适配层(type 1 / 3 / 4) │ ├─ search.ts 多站点并发聚合搜索 │ ├─ category.ts 分类浏览(分类树按祖先链归并大类/子分类 + 叶子 id 逐页拉) │ ├─ detail.ts 详情与线路/剧集解析 │ ├─ live.ts 直播源解析(m3u / txt 分组格式) │ ├─ resolve.ts 播放地址解析(parse 接口 / 嗅探) │ └─ external.ts 外部播放器探测与调用 ├─ preload/ │ ├─ index.ts contextBridge 暴露 api │ └─ index.d.ts 渲染进程类型声明 └─ renderer/ 渲染进程(浏览器环境) ├─ index.html └─ src/ ├─ main.tsx 入口 ├─ App.tsx 路由与整体布局 ├─ styles/ │ ├─ tokens.css 设计变量(颜色/圆角/阴影/间距) │ └─ global.css 全局基础样式 ├─ components/ 通用组件(海报卡/空态/骨架屏/搜索框…) ├─ pages/ │ ├─ Home.tsx 首页(继续观看 / 推荐 / 分类) │ ├─ Search.tsx 聚合搜索 / 分类浏览(按 URL 有无 ?wd= 切换) │ ├─ Detail.tsx 详情与选集 │ ├─ Player.tsx 播放页 │ ├─ Live.tsx 直播 │ ├─ Library.tsx 收藏 / 历史 │ └─ Settings.tsx 配置源与设置 └─ store/ Zustand store ================================================================================ 3. 核心概念与数据模型 ================================================================================ 3.1 ConfigSource 配置源 一条订阅记录,指向一个 JSON 配置文件(远程 URL 或本地文件)。 { id : string 本地唯一 ID name : string 显示名 url : string 远程地址 / 本地绝对路径 kind : "url" | "file" enabled : boolean 是否参与聚合 lastSync : number 上次同步时间戳 raw : object 上次成功拉取的原始 JSON(离线可用) error : string 最近一次同步失败原因 } 3.2 Site 站点(影视源) 一个可直接查询的资源站接口。 { key : string 唯一标识(csp_xxx) name : string 显示名 type : 0|1|3|4 站点类型,见第 4 章 api : string 接口地址 ext : string 扩展参数(部分 spider 需要) jar : string 依赖的 spider 标识 searchable : 0|1 是否支持搜索 quickSearch : 0|1 是否参与快速搜索(首页搜索) filterable : 0|1 是否支持分类筛选 playerType : number 播放器类型(1=普通,2=解析) categories : string[] 站点自带分类名(P1) style : {type,ratio} 列表卡片样式提示 header : object 站点专属请求头 timeout : number 超时秒数 group : string 分组(来自哪个配置源) enabled : boolean 桌面端本地开关 health : number 最近一次连通性测试延迟(ms),-1 表示失败 } 3.3 Vod 影视条目(列表态) { vod_id, vod_name, vod_pic, vod_remarks, vod_year, vod_area, vod_actor, vod_director, type_name, vod_score, site_key, site_name, source_id ← 桌面端附加:来自哪个站点/配置源 } 3.4 VodDetail 影视详情(继承 Vod) { vod_content : string 剧情简介(HTML,需清洗) vod_play_from : string 线路名,用 $$$ 分隔,如 "线路1$$$线路2" vod_play_url : string 剧集,格式见 3.5 lines : Line[] 解析后的线路数组 } 3.5 播放地址字段格式(TVBox 标准,必须兼容) 单条线路内: "第01集$http://a/1.m3u8#第02集$http://a/2.m3u8" 多条线路线: "线路1剧集串$$$线路2剧集串" 分隔符: $$$ 分线路 # 分剧集 $ 分「名称」与「地址」 3.6 Parse 解析接口 { name, type, url, ext } type=1 为 JSON 解析接口: {url}{播放页地址} → {url: 真实地址, header: ...} 3.7 Live 直播 LiveGroup { name, channels: LiveChannel[] } LiveChannel{ name, url, group, logo, epg } ================================================================================ 4. 自定义 JSON 配置格式规范 ★ 核心 ================================================================================ 桌面版同时支持「两种方言」,解析器自动识别,用户不用关心: A. TVBox 兼容方言 直接吃网上现成的订阅文件,零改动 B. 简洁方言 字段更少、type 用可读字符串,适合自己手写 -------------------------------------------------------------------------------- 4.1 A 方言(TVBox 兼容)完整示例 -------------------------------------------------------------------------------- { "name": "我的影视配置", "version": "1.0", "api": "csp_AppYs", "spider": "./spider.jar", "logo": "https://example.com/logo.png", "wallpaper": "https://example.com/bg.jpg", "notice": "本配置仅供学习交流", "sites": [ { "key": "csp_ExampleCms", "name": "示例资源", "type": 3, "api": "https://example.com/api.php/provide/vod/", "searchable": 1, "quickSearch": 1, "filterable": 1, "playerType": 1, "timeout": 20, "header": { "User-Agent": "Mozilla/5.0" }, "style": { "type": "rect", "ratio": 1.78 } }, { "key": "csp_AnotherCms", "name": "备用资源", "type": 3, "api": "https://another.com/api.php/provide/vod/", "searchable": 1, "quickSearch": 0 } ], "parses": [ { "name": "通用解析", "type": 1, "url": "https://parse.example.com/jx?url=", "ext": { "flag": ["qq", "youku", "iqiyi"] } } ], "lives": [ { "name": "默认直播", "type": 0, "url": "./live.txt", "epg": "" } ], "flags": ["qq", "youku", "iqiyi", "mgtv"], "headers": [ { "host": "*.example.com", "header": { "Referer": "https://example.com/" } } ], "ads": ["mimg.0c1q0l.cn", "www.googletagmanager.com"], "doh": [ { "name": "阿里", "url": "https://dns.alidns.com/dns-query" } ] } -------------------------------------------------------------------------------- 4.2 B 方言(简洁版)完整示例 —— 面向手写 -------------------------------------------------------------------------------- { "format": "tvbox-desktop/1", "name": "我自己的配置", "theme": { "accent": "#2563EB", "posterRatio": 0.66 }, "sites": [ { "name": "某资源站", "type": "cms", "api": "https://example.com/api.php/provide/vod/", "search": true, "header": { "User-Agent": "Mozilla/5.0" } }, { "name": "某网页站", "type": "html", "api": "https://example.com/vod/{type}/page/{page}.html", "rules": { "list": ".module-item", "name": "a.module-poster::attr(title)", "link": "a.module-poster::attr(href)", "pic": "img::attr(data-src)", "remarks":"span.module-item-text::text", "search": "https://example.com/search/{wd}/page/{page}.html" } }, { "name": "某聚合接口", "type": "api", "api": "https://example.com/api/{ac}?wd={wd}&pg={page}" } ], "parses": [ { "name": "我的解析", "type": 1, "url": "https://jx.example.com/?url=" } ], "lives": [ { "name": "我的直播", "type": "txt", "url": "https://example.com/live.txt" } ], "externalPlayer": { "command": "", "args": ["{url}"], "prefer": ["PotPlayer", "mpv", "VLC"] } } -------------------------------------------------------------------------------- 4.3 站点 type 取值与桌面端支持策略 -------------------------------------------------------------------------------- type 含义 桌面端策略 --------------------------------------------------------------------------- 3 苹果CMS / MacCMS V10 接口 ✅ 完全支持(主力,生态里 90% 的源是这类) 1 网页型 / JSON 规则型 ✅ 支持(用 rules 规则 + cheerio 解析) 4 影视TV 系 CMS 变体 ⚠️ 按 type3 协议尝试,多数可直接用 0 需配套 spider(jar) 的聚合 ⚠️ 无法执行 Java jar,标记「需 Spider」并跳过; 若配置里给了 api 则降级按 type3 试 2 自定义/其他 ⚠️ 标记为不支持,仅展示 说明:安卓版 TVBox 的 spider 是 dex/jar 字节码,桌面端无法直接运行。 因此本项目的兼容重点放在 type=3(苹果CMS)与 type=1(网页规则)。 这也是现有公开订阅里覆盖度最高的两类。 -------------------------------------------------------------------------------- 4.4 苹果CMS(type=3) 接口协议(桌面端实现依据) -------------------------------------------------------------------------------- 分类列表 {api}?ac=list&t={分类id}&pg={页码} 分类详情 {api}?ac=detail&t={分类id}&pg={页码} 影片详情 {api}?ac=detail&ids={影片id} 关键词搜索 {api}?wd={关键词}&ac=detail 分页搜索 {api}?wd={关键词}&ac=detail&pg={页码} 统一返回: { "code": 1, "msg": "数据列表", "page": 1, "pagecount": 100, "limit": "20", "total": 2000, "list": [ { "vod_id": 123, "vod_name": "片名", "vod_pic": "https://...", "vod_remarks": "更新至20集", "vod_year": "2024", "type_name": "电视剧", "vod_play_from": "线路1$$$线路2", "vod_play_url": "第1集$http://...#第2集$http://...$$$第1集$http://..." } ] } 容错要求: - code 可能为 1/"1"/"ok",统一归一化 - type_name 可能为 "电视剧,国产剧",取第一个 - 部分站点返回 vod_play_from 与 vod_play_url 数量不一致,以短的为准 - 部分站点搜索接口需 ac=detail&wd=,部分只认 ac=detail&ids=,做自动重试 -------------------------------------------------------------------------------- 4.5 桌面端扩展字段(写在任意配置里都生效,安卓端会忽略,不破坏兼容) -------------------------------------------------------------------------------- "tvboxDesktop": { "minVersion": "0.1.0", "theme": { "accent": "#2563EB", "posterRatio": 0.66, "density": "compact" }, "siteOverrides": [ { "key": "csp_ExampleCms", "timeout": 30, "searchable": 1, "header": { "Referer": "https://example.com/" } } ], "externalPlayer": { "command": "", "args": ["{url}"], "prefer": ["PotPlayer","mpv"] }, "home": { "sections": [ { "title": "近期热门", "site": "csp_ExampleCms", "typeId": 1 } ] } } 设计意图:扩展只做「覆盖」不做「新增语义」,任何一份扩展过的配置丢给安卓 TVBox 仍然可用(多余字段被忽略),反过来安卓的配置拿来也能直接跑。 -------------------------------------------------------------------------------- 4.6 配置来源与导入方式 -------------------------------------------------------------------------------- 1) 远程订阅 URL —— 输入地址,一键拉取,支持一键更新 2) 本地 JSON 文件 —— 文件选择 / 直接把 .json 拖进窗口 3) 多源合并 —— 多个配置源同时启用,站点按 key 去重,后面的源不覆盖前面 4) 单站点临时粘贴 —— 设置页可直接粘贴一段站点 JSON 快速试 ================================================================================ 5. 功能模块清单 ================================================================================ 【P0 · 核心链路,第一版必须可用】 M01 配置源管理 - 添加/编辑/删除/启用禁用订阅,远程 URL 与本地文件皆可 - 一键同步、显示站点数量与上次同步时间、失败原因 - 原始配置本地缓存,断网也能用上次的数据 - 配置导入 / 导出(含单个配置源的分享文本) M02 站点管理 - 站点列表:名称 / 类型 / 分组 / 来源配置 / 启用开关 - 搜索、按类型与分组筛选、批量启用禁用 - 连通性测试(发一次 ac=list,显示延迟或失败原因) - 站点排序(决定搜索结果展示顺序) M03 聚合搜索 - 输入即搜(300ms 防抖),并发上限可配(默认 8),单站点超时 10s - 结果按「影视条目」聚合:同一部片子不同站点归到一张卡,卡上标注可用站点数 - 顶部站点筛选 chips,可只看某个站 - 搜索过程中流式返回(哪个站先回就先显示,不用等全部完成) M04 详情页 - 海报 / 片名 / 年份 / 地区 / 演员 / 导演 / 分类 / 评分 / 简介 - 多线路切换 tabs(线路1、线路2…) - 选集网格,支持「正序 / 倒序」切换,支持剧集搜索定位 - 从搜索结果进入时保留返回位置 M05 播放器 - ArtPlayer + hls.js,支持 m3u8 / mp4 - 自定义白色控制条:播放暂停 / 进度 / 音量 / 倍速(0.5-3.0) / 画质 / 截图 / 画中画 / 网页全屏 / 全屏 - 键盘快捷键:空格播放暂停、←→ 快退快进 10s、↑↓ 音量、F 全屏、 N 下一集、P 上一集、Esc 退出播放 - 自动连播下一集、跳过片头片尾(可配)、记忆播放进度 - 播放失败自动尝试下一线路 / 下一个解析 M06 直播 - 解析 m3u / txt 两种格式,支持 #genre# 分组语法 - 左侧分组列表 + 右侧频道列表,点击即播 - GBK 编码自动识别转码 M07 收藏与历史 - 收藏影视,本地持久化 - 观看历史:最近观看、看到第几集、播放进度,支持断点续看 - 首页「继续观看」横向滚动条 M08 自定义 JSON - 完整支持第 4 章两种方言 - 可视化 JSON 编辑器(带语法校验与错误定位) - 导入 / 导出 / 复制分享文本 【P1 · 体验增强】 M09 解析接口(parse) - 网页型播放地址调用解析接口换取真实地址 - 解析失败自动轮询其他解析接口,记录可用性排行 M10 外部播放器 - 自动探测 PotPlayer / mpv / VLC 安装路径 - 一键用外部播放器打开当前剧集,可配置启动参数模板 M11 首页内容位 - 「继续观看」「最近更新」「分类推荐」若干横向内容条 - 数据来源为配置里 tvboxDesktop.home.sections 指定的站点分类 M12 界面设置 - 强调色、海报比例、内容密度(舒适/紧凑)、深色模式(可选) - 窗口尺寸记忆 【P2 · 后期】 M13 下载(m3u8 合并,依赖 ffmpeg,需检测环境) M14 弹幕(第三方弹幕库对接) M15 投屏 DLNA M16 豆瓣等榜单推荐位 ================================================================================ 6. 界面设计规范(纯白风格) ================================================================================ 6.1 设计变量 背景 #FFFFFF 主背景 背景次级 #F7F8FA 卡片底 / 侧栏 / 输入框 背景三级 #F1F3F5 悬停态 边框 #ECEEF2 分割线(1px) 文字主 #1F2329 文字次 #646A73 文字弱 #8F959E 强调色 #2563EB 链接 / 选中 / 主按钮(可在设置里改) 成功 #16A34A 警告 #D97706 危险 #DC2626 圆角 6 / 8 / 12 / 16 阴影 0 1px 2px rgba(0,0,0,.04) 极淡,只在悬停时加深到 0 8px 24px rgba(0,0,0,.10) 字体 "Segoe UI", "Microsoft YaHei UI", system-ui, sans-serif 数字字体 tabular-nums(播放进度、评分对齐更好看) 原则:界面 95% 是白色与浅灰,只有强调色一处彩色,保证「纯白但不单调」。 6.2 整体布局(电脑宽屏优先,1440×900 设计基准) ┌──────────────────────────────────────────────────────────────────────┐ │ 顶栏 56px [Logo] [ 全局搜索框 ................ ] [设置] [最小化组]│ ├────────┬─────────────────────────────────────────────────────────────┤ │ 侧栏 │ │ │ 200px │ 主内容区(自适应) │ │ 可收成 │ │ │ 64px │ │ │ │ │ │ 首页 │ │ │ 搜索 │ │ │ 直播 │ │ │ 收藏 │ │ │ 历史 │ │ │ 设置 │ │ └────────┴─────────────────────────────────────────────────────────────┘ 6.3 各页面要点 首页 - 「继续观看」横向卡片条(16:9 缩略图 + 进度条 + 看到第几集),无记录时隐藏 - 内容条:每行一个栏目,标题左对齐 + 右侧「更多」 - 海报网格:竖版 2:3,自适应列数(内容区宽 1200px 时约 6 列, 窗口越大列越多,不放大单卡到失真),卡片悬停浮起 + 右上角「立即播放」 - 卡片信息:片名(1 行省略)+ 备注(更新至xx集 / 已完结) 搜索页 - 顶部站点筛选 chips(横向可滚动) - 结果默认按「影视」合并展示,可切换为「按站点」分组展示 - 骨架屏占位,某站点返回后即时插入 详情页 - 左:海报 260px 宽 2:3,圆角 12,淡阴影 - 右:片名(28px) / 元信息行 / 评分 / 简介(默认 3 行,可展开) - 下部:线路 tabs(下划线动画)+ 选集网格(自适应,推荐每行 10-14 个) - 选集按钮:正方形小卡,正在播放的高亮强调色 播放页 - 播放器自适应宽度,最大高度占满,纯黑背景 - 右侧 320px 剧集抽屉(可折叠),当前集高亮 - 顶部返回 + 片名 + 线路切换下拉 所有列表页 - 空态:居中浅灰插画位 + 一句引导文案 + 主按钮 - 加载态:骨架屏(不用转圈),避免白屏跳动 - 错误态:说明原因 + 「重试」 6.4 内容密度(体现「内容丰富」) - 默认「紧凑」密度:卡片间距 12px,行距紧凑 - 一屏目标:首页可见 ≥ 24 张海报;详情页可见 ≥ 40 个选集按钮 - 侧栏可一键收起,给内容区让出 136px ================================================================================ 7. 关键流程 ================================================================================ 7.1 启动流程 读本地配置缓存 → 若超过 N 小时则后台静默同步 → 渲染首页 (首屏不等待网络,先出缓存,网络回来再补) 7.2 聚合搜索流程 输入关键词(顶部的全局搜索框) → 取所有 enabled && searchable 的站点 → 并发池(8) 逐个发起:{api}?wd={kw}&ac=detail → 每个站点返回后立刻归一化并推送到渲染进程(流式) → 全部结束后做同名合并(见 7.2.1):合成一张卡,卡上记录 [{site_key, vod_id, vod_name, vod_remarks}] 列表 → 用户点卡片 → 用信息量最高的那个站点进详情,详情页可切站点 7.2.0 分类浏览(用户要求「变成目录例如电影动漫一类的」) 左侧导航第二项,页面本身没有搜索框 —— 找片名走顶部全局搜索框, 这一页是「不知道看什么」时用的目录。同一个 Search.tsx 按 URL 上有无 ?wd= 分成两种模式:有就是聚合搜索,没有就是分类浏览。 打开时对每个 type 3/4 的启用站点请求一次 {api}?ac=list, 从返回的 class 数组拿分类树,接着: · 按名字归并成统一大类:电影 / 电视剧 / 动漫 / 综艺 / 纪录片 / 短剧 / 体育 / 少儿(顺序固定) · **归并要对着整条祖先链做,不能只看顶层**。真实站点会把类型混着挂: 「记录片」挂在「电影片」下面(而且写的是「记录」不是「纪录」, 漏这个字它就会留在电影里)、「短剧」挂在「连续剧」下面。只看顶层 的话这些全都会进错桶。 · **「动画片」归哪儿要看父分类**:挂在「动漫片」下面归动漫,挂在 「电影片」下面则是动画电影,要跟着父分类归到 电影 → 动画 —— 光速 / 素博 的同类内容叫「动漫电影」且本来就在电影里,不这么处理 同一类内容会裂成两个区(这是用户报的「只显示几个子分类」的 其中一面)。例外精确列在 LEAF_FOLLOWS_PARENT 里,只对祖先链 匹配,别的站点真把「动画片」挂在「动漫片」下时不受影响。 · **分类名命中 SKIP 就整棵子树丢掉**。SKIP 仍然是 解说 / 演员 / 明星 / 资讯 / 新闻 / 预告 / 花絮 / 伦理 / 福利 / 写真 / 片花 / 榜单,但**判定沿祖先链生效**:非凡 / 量子 / 天堂 的 「伦理片」是电影片的**子分类**(光速 / 素博 才是顶层),只挡顶层 名字的话这三个站的伦理片会漏进电影里 —— 这是实际出现过的 bug。 过滤只按分类名,不做片名关键词兜底,而且只在分类浏览里生效, 聚合搜索不受影响。 · **大类下面再分子分类**(用户要求「有一部分影视完全分错区重新分」 → 答复「把分区扩大」)。子分类归一表 SUBS 把各站的叫法收进 统一名字:电影 → 动作 / 喜剧 / 爱情 / 科幻 / 恐怖 / 剧情 / 战争 / 动画,电视剧 → 国产 / 香港 / 台湾 / 韩国 / 日本 / 欧美 / 泰国 / 海外,动漫 → 国产 / 日本 / 欧美 / 港台 / 海外 / 动画电影, 综艺 → 大陆 / 港台 / 日韩 / 欧美,体育 → 足球 / 篮球 / 网球 / 台球 / 其他,短剧 → 擦边短剧 / 古装仙侠 / 现代都市 / 穿越年代 / 言情总裁 / 重生民国 / 反转爽剧 / 脑洞悬疑 / 短剧。 归一表里没有的叶子就直接用叶子自己的名字(实际站点里出现过 「AI漫剧」这种表外叶子,会原样成为一个子分类)。 · **父分类必须展开成叶子**:实测父分类 id 查不出任何东西 (t=1 返回 0 条),leafIds() 递归取到最底层的 id · **分类树缓存两头都要能作废**。主进程 classCache 按站点 key 存、 TTL 10 分钟(同一批请求会去重);渲染进程还有一份 categories。 换整套订阅时 key 变了能自然失效,但**原地改源地址 / 禁用某个站点** 时 key 没变,两边都还认旧目录 —— 用户报的「子分类有 bug 只显示 几个子分类」根因就在渲染进程那份:Search.tsx 里「categories 非空 就不再拉」的守卫把旧数据锁死了。现在站点集合一变就走 staleCatalog() 清掉渲染进程的 categories 与 browse,主进程侧也在 add / update / remove / sync / syncAll 五个 IPC 里主动 clearCategoryCache()。 选中一个大类(或它的某个子分类)后,向每个站点发 {api}?ac=detail&t=<叶子id>&pg=N,ac 用 detail 是为了顺带把 vod_play_url 拿回来,进详情页不用再请求一次。 **重复的 t 参数是「最后一个生效」而不是 OR** —— 这条是关键, 早先按「服务端 OR」设计过,实测是错的: t=6(动作片) total 4558,返回动作片 t=7(喜剧片) total 7176,返回喜剧片 t=6&t=7 total 7176,返回**全是喜剧片** ← 只有最后一个生效 t=6&t=7&t=8 total 2121,返回爱情片 t=6,7(逗号) total 4558,只认第一个 所以「全部」是**每个叶子各发一次请求**(用 cursor + worker 并发池, 并发数取设置里的 concurrency),拿回来用 interleave() 按子分类 **交替穿插**合并(不是首尾相接,否则第一屏全是同一类型), 再按 vod_id 去重、截断到 limit。模板式站点只有一个 {t} 槽位, 只取第一个叶子。 因为「全部」代价高(电影有 8 个叶子 × 5 个站点 = 40 个请求, 实测 4–8 秒),点进多子分类的大类时**默认落在第一个子分类**上, 想全看再点「全部」。 页数优先读接口自己报的 pagecount:采集站每页固定 20 条,和请求里的 limit 不一致,按「本页满没满」猜会永远算出 1 页。 站点内取最浅子分类的 pagecount,跨站点取最大值。 **向下滚动自动加载**(用户要求「每次往下翻电影的时候整成自动加载」): 底部放一个哨兵 div,用 IntersectionObserver(rootMargin 提前 500px) 把「是否进入视口」记成一个布尔 state,再由一个 effect 判断要不要真发请求。 不直接在回调里发请求,是因为「加载完新一页后哨兵可能还在视口里」这种 情况不会产生新的交叉事件,光靠回调会卡住不再继续加载。 两个坑: · effect 的依赖必须和哨兵 div 的渲染条件完全一致(含 !browse.running)。 否则首屏还在请求、div 尚未挂载时 effect 就跑了一次、拿到空 ref 直接 返回;等 running 变 false、div 真的出现时依赖没变、effect 不再重跑, 观察器永远没挂上 —— 表现为滚到底什么都不发生。 · 失败时页码不前进,必须靠 error 标记停下来,否则哨兵一直在视口里 会无限重试同一页,把站点打爆。界面上显示原因 + 「重试」按钮。 新一页接在已有结果后面(不是替换),并用 site_key + vod_id 去重 —— 有些站点翻页是假的,会整批返回同一页。 7.2.1 同名合并规则(用户要求「把每个源的重复资源合成一个」) 分组 key = normalizeName(vod_name): 全角转半角 → 去掉尾部别名括号 → 去噪声词(高清/超清/全集/国语版…) → 去标点与空格 → 转小写 季数、部数、副标题保留,保证「第一季 / 第二季 / 之帝王业」不会被合成一部。 尾部括号里若含「第N季/部/集/篇、特别篇、番外、前传、后传」则不去掉。 每组内先按站点收敛:同一站点只留一条,排序依据是 「有海报(+4) > 有备注(+2) > 有评分(+1),同分取名字短的」。 代表条目(显示用的片名与海报)取收敛后信息量最高的那条, 其余条作为该卡的其它片源。 排序:与关键词的匹配度(完全相等 < 前缀 < 包含 < 其它)→ 片源数多优先 → 信息量 → 中文片名排序。 7.2.2 解说过滤(用户要求「去除掉每个源的电影解说」) 两条线索任一命中即判定为二创内容: · 片名 —— 解说 / 速看 / 盘点 / 混剪 / 拆解 / 影评 / 剧情介绍 / 一口气看完 / 分钟看完 · 分类 —— vod_class 或 type_name 里含上述词(多数站点标「影视解说」) 只按片名判断会漏掉片名干净、靠分类标记的条目,所以要两条都看。 网页规则站拿不到分类字段(searchHtml 写死 type_name: ''),只能按片名判断。 默认隐藏并计数,搜索页副标题写明「已挡掉 N 条解说」, 搜索页与设置页都能关掉。不做时长判断——列表接口通常不返回时长。 7.3 详情流程 选中 (site_key, vod_id) → {api}?ac=detail&ids={id} → 解析 lines:vod_play_from.split('$$$') 与 vod_play_url.split('$$$') 对齐 → 每条线路内 split('#') 得剧集,每集 split('$') 得 [名称, 地址] → 默认选中第一条「首集地址看起来是直链」的线路的第一集 (采集站常把网页分享页放在第 1 条线路,盲选会黑屏) → 详情页「选择片源」区块列出这部片子在其它站点上的条目,点一下换源 7.4 播放流程 得到剧集地址 url → 若已是 http(s) 且以 .m3u8/.mp4 结尾 → 直接播 → 若为网页地址且站点 playerType=2 / 配置了 parses → 调解析接口 GET {parse.url}{encodeURIComponent(url)} → {url, header} 失败则轮询下一个解析接口(最多 3 个) → 仍失败 → 提示「改用外部播放器打开」 → 播放器就绪后写入历史(进度每 10s 落盘) → ended 事件 → 自动下一集 播放页侧栏「片源」区块:列出这部片子在各个站点的条目,点一下换源继续看。 换源链接只带 /0/0,进入后由播放页自动跳到该源里「能直接播」的那条线路; 没走过搜索就直接打开播放页时列表为空,提供「找其它片源」按片名现搜一次。 播放器下方的地址整块可点,点了用系统默认浏览器打开该地址; 旁边另有「复制地址」按钮走剪贴板。 注意:Artplayer 的 option 校验器要求 type 必须是字符串, 显式传 type: undefined 会抛「'option.type' require 'string' type」并把 整棵 React 树卸载。所以非 m3u8 时不要传 type/customType,让它按扩展名自己推断。 7.5 网络与反爬 - 所有请求走主进程,默认带浏览器 UA - 站点级 header、全局 headers 规则(按 host 通配匹配)依次应用 - 超时默认 20s,失败重试 1 次(指数退避) - 图片走渲染进程直连,失败降级为占位图 7.6 电视直播流程 配置源里的 lives 字段(type 0 = txt,1 = m3u)→ 并发拉全部直播源 → 按内容嗅探格式(出现 #EXTM3U / #EXTINF 就当 m3u,否则当 txt) → txt:`#genre#` 行开一个分组,其余行按「名称,地址」拆; 地址右侧不像 URL 时再按 `#` 切一次 m3u:#EXTINF 的属性段在最后一个逗号之前,显示名在逗号之后; 取 tvg-name / group-title / tvg-logo → 按频道名精确合并成一卡多线路(同一地址去重) → 分组按频道数降序,`其它` 永远排最后 主进程侧有一份 10 分钟缓存(换配置源时由 index.ts 主动作废)。 渲染进程侧刻意**不**再缓存一份:早先写成「内存里有就直接返回」, 结果同步完新订阅再进电视直播,看到的还是上一个源的分组,只有重启才好。 现在每次进页面都问一次主进程,它缓存还新鲜时就是一个来回的 IPC。 同一个源的失败提示只会弹一次,否则每次进页面都重复弹。 **作废缓存光 clear 是不够的**:很可能正好有一次 loadLive 还在飞, 它跑完会把上一个源的结果写回 cache,于是「换完订阅还是旧分组」又出现。 这类竞态只在换源和首次加载撞上时才复现,表现成「自检第一次跑必挂、 第二次才过」。现在用一个 generation 代次号:loadLive 开头记下当时的 代次,写回缓存前比一次,换过源就不写(本次结果照旧返回给调用方)。 category.ts 的 classCache / inflight 是同一个坑、同一套修法。 点频道后播放器会自动滚回视野。频道多的时候(「地方频道」一个分组就有 247 个)点列表靠下的频道,播放器早就滚出屏幕了,不拉回来就只看得到声音。 用 scrollIntoView({block:'nearest'}),播放器本来就在视野里时不做任何滚动。 trigger 用一个自增计数而不是 picked 本身 —— 重复点同一个频道时 picked 的引用没变,拿它当依赖 effect 不会重跑。 7.6.1 房间号频道(huya:// 与 douyin://) 虎牙、抖音这类平台的直播地址带防盗链签名、几小时就失效,写进直播源里 第二天就是死链。所以直播源里只写房间号: 游戏赛事,#genre# danking直播,huya://10188 `huya://10188` = 虎牙房间 10188;`douyin://` = 抖音直播间。 只有用户点开这个频道时才走一次 IPC 去平台换真地址,换好了才构造播放器。 地址格式判定放在 shared/liveUrl.ts(主进程和渲染进程都要认),主进程那边 的解析在 services/streamResolve.ts。 另有一路「内置自定义频道」直播源(live.ts 的 BUILTIN_LIVE), 即使没配任何订阅,游戏赛事分组里也一定有 danking直播。 live.ts 的地址识别正则因此要从 https?/rtmp/rtsp/rtp/udp/file 扩到带 huya/douyin,否则 `huya://10188` 会被当成分隔符串切坏。 分组名归一:源里的 `•游戏「赛事」`、`•影视「轮播」`、`•咪咕「移动」` 这类带装饰符的名字,先 stripDecorator 去掉开头的 •·・*-— 与「」【】《》[](), 再查 GROUP_ALIAS 别名表映射成 `游戏赛事` / `影视轮播` / `咪咕移动`。 7.6.2 三个必须记住的坑 (1) 虎牙 TX / AL 两条线给的是「主播放列表」(只有 #EXT-X-STREAM-INF), 里面那条变体地址被改写成 `http://<边缘节点IP>/tx.hls.huya.com/src/…` —— 浏览器带着 `Host: ` 去拉**一律 403**。还原主机名、补 Origin、补 Referer 全试过,还是 403。而 HS 那条直接给「媒体播放列表」(有 #EXTINF), 分片是相对路径,实测 200 + video/MP2T。 所以解析器要逐个探测,优先挑含 #EXTINF 的真媒体列表,主列表只当兜底, AL 排最后。判据不能只看「有没有 #EXTM3U」,否则会选到播不了的主列表。 (2) `Referer` 是浏览器的 forbidden header。 `xhr.setRequestHeader('Referer', …)` 会被**静默忽略** —— hls.js 实际发出去的是页面自己的来源(开发时 http://localhost:5173/), CDN 因此对分片回 403,而播放器**不报任何错**:readyState 停在 0、 video.error 恒为 null,只表现为黑屏,极难查。 修法只能在会话层补:主进程用 session.defaultSession.webRequest.onBeforeSendHeaders 给匹配的请求写上头。匹配要按**域名后缀**而不是 host,因为虎牙把 真实主机名塞进了 path(`http:///tx.hls.huya.com/src/…`)。 https 才补 Origin(http 下实测不需要,多补反而可能被拒)。 (3) 抖音的取流接口不要签名:先进 https://live.douyin.com/ 拿 ttwid, 再调 webcast/room/web/enter/(aid=6383、web_rid=, 带 cookie 与 referer)取 hls_pull_url_map,status 2 = 直播中、 4 = 本场已结束。但它的**分区 / 用户列表接口全返 444 Access Denied** (要 a_bogus 签名),首页和用户主页又是客户端渲染、没有 SSR 的 web_rid —— 所以**没法自动发现某人的抖音直播间号**,只能由用户提供。 7.7 系统代理:一个长得像「播放器坏了」的环境问题 界面里的海报和视频走 Chromium,主进程的请求走 Node,而两者对系统代理的 处理**不一样**:Chromium 听 Windows 的代理设置,Node 的 fetch 不读它。 所以当 Windows 的系统代理开着、指向的代理软件却没在跑时(Clash 内核退了、 ProxyEnable 还留在 1),会出现: · 搜索 / 详情 / 分类 / 直播分组全部正常 —— 它们走主进程; · 但界面里**所有**图片和视频都黑,控制台一片 net::ERR_PROXY_CONNECTION_FAILED。 实测过一次:系统代理 127.0.0.1:7897、端口无人监听;渲染进程每个请求都 ERR_PROXY_CONNECTION_FAILED,而主进程直连 img.dytt-tupian.com / vip.dytt-cinema.com/…/index.m3u8 / api.ffzyapi.com 全是 200、600–720ms。 services/proxy.ts 在建窗口之前跑一次:resolveProxy 问出系统代理链 (形如 "PROXY 127.0.0.1:7897"),对里面每个 host:port 做 800ms 的 TCP 探测,**只要有一个在监听就照旧走系统代理**,一个都连不上才 session.defaultSession.setProxy({ mode: 'direct' }) 并打一条 [proxy] 警告。 注意每次启动只判断一次:启动时代理是死的、之后又把代理打开了, 要重启应用才会用上。反过来,代理一直活着时这条逻辑完全不起作用。 7.8 AI 剧情总结(用户要求「在看视频链接的下面加一个 ai 总结」) 位置:播放页视频地址下面。**点了才会请求** —— 进来一集就自动调一次既白花钱、 用户也可能根本不想看,所以不做后台预取。 链路:components/AiSummary.tsx(交互)→ IPC ai:summary / ai:summary-visual → services/ai.ts(发请求)。API Key 存在 data/settings.json 的 settings.ai.apiKey,**只在主进程里用**,渲染进程拿不到,也不会随请求外传。 两条路,界面上是两个按钮: (一)看一遍再总结(默认动作,用户原话是「让deepseek直接看一遍当前剧集 而不是推测」)。渲染进程先用 utils/frames.ts 从正在播的