dsh-tv-player 0.0.0-stage → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-tv-player contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# dsh-tv-player
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **非官方、社区维护项目**：本插件与 DeepSeek Harness 官方无任何关联，仅作为个人学习/自用工具提供。
+
+DSH 电视插件 —— 在 DeepSeek Harness 里直播 **8 个确定稳定的频道**（浙江 / 延边 / 香港 / 内蒙古 / 河北 / 东方卫视 + CCTV-9 纪录 / CCTV-12 社会与法），白底黑字的播放条与全宽电视画面，写代码时把电视放在聊天输入框上方，是 **Vibe coding 时的好伴侣**。
+
+参考 `dsh-music-player` 的双面结构：Host 端跑频道目录 + 同源直播流代理 + `tv_play` 模型工具，Web 端用 `<video>` + hls.js 播放。
+
+## 特性
+
+- **8 个精选频道**：浙江 / 延边 / 香港 / 内蒙古 / 河北 / 东方卫视走各台官方 CDN、音轨为浏览器可解码的 AAC；CCTV-9 纪录 / CCTV-12 社会与法走公开中继源（含备用源）；每个频道带多个候选流 URL，失效自动切换。
+- **临时频道搜索**：频道面板标题栏 🔍 一键展开，自动列出公开 IPTV 源里可播放的频道（央视/卫视/凤凰）；点结果加入底部「📌 临时频道」栏，可播放/移除。
+- **白底黑字 + 中英双语**：播放条、电视画面区、频道面板统一白底黑字；所有按键提示与面板文字均为「中文 English」双语。
+- **频道面板**：锚定在电视画面区内右侧（不遮挡输入框），含「★ 我的收藏」「卫视」「央视」分组、🔍 临时频道搜索与「📌 临时频道」栏。
+- **收藏夹**：频道行尾 ⭐ 一键收藏/取消，持久化在 Host（`~/.dsh/tv-player-favs.json`）。
+- **EPG 节目单**：频道列表显示「现在 · 节目名」（fanmingming e.xml，XMLTV 格式，落盘缓存 6 小时）。
+- **定时（换台 / 关电视 / 关电脑）**：面板底部配置「每天/指定星期 · 时刻」的自动动作——切到某频道、停止播放、或关机（`shutdown /s /t 30`，30 秒内可 `shutdown /a` 取消）；Host 端 Node 定时器自维护、脱离会话存活，持久化 `~/.dsh/tv-player-schedule.json`。
+- **多源容灾**：同名频道累积多个候选流 URL，播放中某个源失效时自动切换下一源。
+- **多标签页统一播放器**：同时开多个 DSH 标签页时只有一页出声（BroadcastChannel 协同 + 心跳失效检测）。
+- **初始为关电视状态**：启动/刷新后不自动恢复频道、不显示画面；需要时点 ▶（随机播一个频道）或选台开播。
+- **`tv_play` 模型工具**：在对话框说「播放浙江卫视」即可开播；支持 pause/resume/stop/mute/unmute/next/prev 动作。
+- **同源流代理**：Host 端重写 m3u8 分片 URL 到同源 `/dsh-tv/segment`，规避上游无 CORS 的跨域问题；纯透传、不转码、不落盘。
+
+## 安装
+
+### 方式一：本地 tgz（自用 / 内部分发）
+
+```sh
+# 1) 打包
+npm pack            # 产出 dsh-tv-player-<version>.tgz
+```
+
+然后编辑目标 profile 的 `package.json`（例如 `~/.dsh/profiles/<profile>/package.json`）：
+
+1. 在 `dependencies` 里加：
+   ```json
+   "dsh-tv-player": "file:D:/绝对路径/dsh-tv-player-<version>.tgz"
+   ```
+2. **务必**在 `dsh.profile.bundles` 里加 `"dsh-tv-player"`（漏了它插件不会被加载，界面/路由都不会出现）：
+   ```json
+   "dsh": { "profile": { "bundles": [ "...", "dsh-tv-player" ] } }
+   ```
+3. 安装并重启：
+   ```sh
+   pnpm install        # 或 dsh plugin --profile <profile> add file:<tgz 路径>
+   # 然后重启 DSH
+   ```
+
+### 方式二：发布到 npm 后
+
+```sh
+dsh plugin --profile <profile> add dsh-tv-player
+```
+
+安装后重启 DSH，打开 Web GUI：聊天输入框上方会出现「DSH 电视」播放条。
+
+## 使用
+
+### 对话开播
+
+- 「**播放浙江卫视**」「**播放东方卫视**」→ agent 调 `tv_play` 匹配频道并开播。
+- 「**暂停电视 / 继续 / 停止 / 静音 / 下一个频道**」→ agent 调 `tv_play` 的传输动作。
+- 首次可能被浏览器拦截自动播放，在播放条点一次 ▶ 解锁即可。
+
+### 播放条
+
+- ▶/⏸ 播放暂停、🔊 静音、音量滑块、⏮ ⏭ 上/下一个频道、⏹ 停止、👁/🙈 显示/隐藏电视画面、📺 频道列表。
+- 无当前频道时点 ▶ 会**随机播放一个频道**。
+
+### 频道面板
+
+- 播放条「📺」打开频道面板（锚定在电视画面区内右侧）。
+- 点任意频道即播放；行尾 ⭐ 收藏/取消收藏；当前频道高亮并带「LIVE」徽标。
+- 底部「⏰ 定时」添加三类规则：**换台 / 关电视 / 关电脑**。
+
+## 配置
+
+`cordis.patch.yml` 里可覆盖（Schemastery 校验字段）：
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `enabled` | `true` | 主开关，`false` 不挂载任何能力 |
+| `sources` | `[]`（空） | 在线 m3u 目录源列表；默认关闭（精选 8 频道模式） |
+| `epgUrl` | fanmingming e.xml | EPG（XMLTV）数据源 |
+| `epgTtlMs` | `21600000` | EPG 落盘缓存 TTL（毫秒） |
+| `catalogTtlMs` | `1800000` | 目录缓存 TTL（毫秒） |
+| `timeoutMs` | `15000` | 单次上游请求超时 |
+| `retries` | `1` | 目录/播放列表拉取重试次数 |
+| `maxChannels` | `400` | 收录频道上限 |
+
+## 架构
+
+```
+Host（lib/index.js + channels.js + proxy.js + config.js + epg.js）
+ ├─ 频道目录：内置 8 个精选频道（多候选 URL）→ 归类去重 → 缓存
+ ├─ /dsh-tv/playlist  拉上游 m3u8 并重写分片/子列表/密钥 URL 到同源
+ ├─ /dsh-tv/segment   分片逐字节透传（附 Referer/UA 防盗链）
+ ├─ /dsh-tv/vendor/hls.min.js  内嵌 hls.js（客户端 <script> 注入）
+ ├─ 定时器：换台 / 关电视（下发 stop）/ 关电脑（shutdown）
+ └─ tv_play 工具 → pendingIntent → 客户端轮询 /dsh-tv/intent 领取
+
+Web（lib/client.js）
+ ├─ <video> + hls.js（Safari 回退原生 HLS）
+ ├─ 电视画面 + 播放条（conversation.input.dock，白底黑字）
+ └─ 频道面板（锚定电视画面区内右侧，含定时规则）
+```
+
+与音乐播放器一致：Host 端 `webServer.register({ kind:'prefix', path:'/dsh-tv', handler })` 挂路由，`ctx.tools.register` 挂工具；Web 端 `slots.inject` 注入 UI，轮询 `/dsh-tv/intent` 接收播放意图。
+
+> **为什么需要同源代理**：IPTV 直播多为 HLS，上游通常不返回 CORS 头，浏览器 `<video>`+hls.js 直接跨域拉流会被同源策略拦截；Host 端把分片 URL 重写到同源路径后即可直接播放，同时给上游补 `Referer`/`User-Agent` 满足防盗链。
+
+## 合规声明
+
+- 播放的是各电视台 / 运营商**公开直播流**（卫视走各台官方 CDN，CCTV-9/12 走公开中继源），目录为开放数据（社区维护）；**不录制、不二次分发、不绕过付费墙 / DRM**，内容版权归电视台 / 版权方。
+- 仅供**个人收看 / 学习研究**使用，请遵守各台站服务条款与**所在国家 / 地区法律**；本项目作者不承担由此产生的任何责任。
+- **不保证频道持续可用**：直播源由第三方公开提供（含中继源），可能随时变更、失效、受地理限制或存在画质/稳定性差异，插件作者不对此负责。
+- 「定时关电脑」会调用系统 `shutdown` 命令，属**明确授权的本地操作**，请谨慎使用。
+- 本插件内含第三方组件 **hls.js**（Apache-2.0），详见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
+
+> 以上为合规提示，不构成法律意见。
+
+## 开发
+
+```sh
+npm pack            # 产出 dsh-tv-player-<version>.tgz
+dsh plugin --profile <profile> add file:<tgz 路径>   # 安装
+```
+
+修改 `lib/` 后**升版本号**重新打包安装（pnpm 对同版本 file 依赖不重取）；仅客户端改动可刷新页面生效，Host 改动需重启 DSH。
+
+## 回滚（卸载）
+
+```sh
+# 1) 从 profile 移除依赖
+dsh plugin --profile <profile> remove dsh-tv-player
+# 2) 编辑 profile 的 package.json，从 dsh.profile.bundles 里删掉 "dsh-tv-player"
+# 3) 重启 DSH
+```
+
+或直接用面板：设置 → 插件管理 → 停用/移除 `dsh-tv-player`。改动仅限该 profile，卸载后即恢复原状。
+
+## License
+
+[MIT](LICENSE)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,45 @@
+# Third-Party Notices
+
+本插件（dsh-tv-player）分发时包含以下第三方组件。各组件的版权归其各自作者所有，许可协议如下。
+
+---
+
+## hls.js
+
+- **名称**：hls.js
+- **版本**：1.5.20（内置于 `lib/vendor/hls.min.js`）
+- **许可**：Apache License 2.0
+- **版权**：Copyright © the hls.js contributors
+- **源码**：https://github.com/video-dev/hls.js
+
+HLS 流播放功能依赖 hls.js。hls.js 依据 **Apache License 2.0** 授权分发。
+
+### Apache License 2.0（全文见 https://www.apache.org/licenses/LICENSE-2.0）
+
+```
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions. ...（完整条款请见上方链接）
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
+
+> 说明：为便于阅读，上表为 Apache-2.0 许可的摘要性引用；完整、具有法律效力的许可文本以官方链接为准。本插件对 hls.js 未做任何修改，仅作为客户端依赖内置分发。
+
+---
+
+除上述第三方组件外，本插件的其余代码均为原创，依据 MIT 许可分发（见 `LICENSE`）。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-tv-player bundle patch: inserts the dual-face plugin row into the web
+# profile roster. The node half (exports ".") runs in the host process (live
+# stream channel catalog + same-origin HLS/segment proxy + the tv_play model
+# tool), and the dsh.client declaration in package.json loads the browser half
+# (exports "./client") in the web GUI.
+- insert:
+    - id: tv-player
+      name: 'dsh-tv-player'

package/lib/channels.js

@@ -0,0 +1,348 @@
+/**
+ * lib/channels.js — 直播频道目录模块（纯 Node，零第三方依赖）。
+ *
+ * 数据来源分两层：
+ *   1) 内置「兜底目录」CURATED_CHANNELS：打包时实测可用的精选频道（央视 / 凤凰 / 主流卫视），
+ *      保证在 GitHub 等目录源不可达时插件仍能开箱即用；
+ *   2) 「在线目录」SOURCES：社区维护、每日更新的 IPTV m3u 列表（fanmingming/live 与
+ *      best-fan/iptv-sources 等，开放数据）。启动/首次调用时拉取并解析，得到的实时
+ *      直播 URL 优先于兜底目录（更「新鲜」，频道失效后会被每日更新纠正）。
+ *
+ * 合规：播放的是各电视台/运营商公开直播流，目录为开放数据；不录制、不二次分发、
+ * 不绕过付费墙/DRM，内容版权归电视台/版权方。仅个人收看/学习使用。
+ *
+ * m3u 解析：逐行读取 #EXTINF 与后续 URI 行，抽取 tvg-name/tvg-logo/group-title 与
+ * 显示名，按 group-title 归类（央视频道 / 卫视频道 / 凤凰 / 其他）。
+ */
+
+// 吉林电信 tsfile 源（222.169.85.8:9901，1080p AAC；晚高峰可能拥塞，仅作备用）。
+const JL = (code) => 'http://222.169.85.8:9901/tsfile/live/' + code + '_1.m3u8?key=txiptv&playlive=1&authid=0'
+
+// 精选频道目录：6 个稳定卫视 + CCTV-9/12（快的源排前面作主源）。
+// 每个频道带多个候选流 URL（`urls`），播放时某个源失效会自动切换下一源。
+// group: cctv(央视) | satellite(卫视) | other(其他)
+export const CURATED_CHANNELS = [
+  { id: 'sat-zj', name: '浙江卫视', group: 'satellite', urls: [
+    'http://ali-xwl.cztv.com/live/channel011080Plxw.m3u8',
+    'http://ali-xwl.cztv.com/live/channel01720Plxw.m3u8',
+  ] },
+  { id: 'sat-yb', name: '延边卫视', group: 'satellite', urls: [
+    'https://srs.iyb983.cn/video/CYS/index.m3u8',
+  ] },
+  { id: 'sat-hk', name: '香港卫视', group: 'satellite', urls: [
+    'https://hkstv.tv/api/m3u8-proxy?url=http%3A%2F%2Fwebcast.hkstv.tv%2Flivestream%2Fmutfysrq%2Fplaylist.m3u8',
+  ] },
+  { id: 'sat-nmg', name: '内蒙古卫视', group: 'satellite', urls: [
+    'http://play1-qk.nmtv.cn/live/1769652018126032.m3u8',
+  ] },
+  { id: 'sat-hb', name: '河北卫视', group: 'satellite', urls: [
+    'http://event.pull.hebtv.com/jishi/weishi_tingyun.m3u8',
+  ] },
+  { id: 'sat-df', name: '东方卫视', group: 'satellite', urls: [
+    'http://bp-resource-dfl.bestv.cn/155/3/video.m3u8',
+  ] },
+  { id: 'cctv9', name: 'CCTV-9 纪录', group: 'cctv', urls: [
+    'https://v4-e6b1c5baf4e240fe63adbf68dda23435.livehwc4.com/play.kankanlive.com/live/1698423397390920.m3u8?sub_m3u8=true&edge_slice=true&user_session_id=9418688afb7b99a56db1a3fb8f0fda52',
+    JL('0009'),
+  ] },
+  { id: 'cctv12', name: 'CCTV-12 社会与法', group: 'cctv', urls: [
+    'http://74.91.26.218:82/live/cctv12hd.m3u8',
+    JL('0012'),
+  ] },
+]
+
+// 最终目录白名单：只保留这些「确定稳定」的频道（过滤掉在线源里的其它频道）。
+export const STABLE_WHITELIST = [
+  'CCTV-9', 'CCTV-12',
+  '浙江卫视', '延边卫视', '香港卫视', '内蒙古卫视', '河北卫视', '东方卫视',
+]
+
+// 在线目录源：默认关闭（只保留上面的 6 个精选卫视）。
+// 如需扩充，可在播放面板底部「自定义 m3u 源」粘贴 IPTV 列表 URL，或在此数组加入。
+export const SOURCES = []
+
+// 「搜索频道」时使用的公开 IPTV 源（比精选目录更全，供按频道名查找可播放频道）。
+export const SEARCH_SOURCES = [
+  'https://cdn.jsdelivr.net/gh/best-fan/iptv-sources@master/cn_all_status.m3u8',
+  'https://raw.githubusercontent.com/best-fan/iptv-sources/master/cn_all_status.m3u8',
+]
+
+/** 按名称/关键词在一个频道列表里搜索（供「搜索频道」用）。 */
+export function searchChannels(query, channels) {
+  const q = String(query || '').trim().toLowerCase()
+  if (q === '') return []
+  const qn = q.replace(/\s+/g, '')
+  return (channels || []).filter((c) => {
+    const name = String(c.name || '').toLowerCase()
+    const key = String(c.id || '').toLowerCase()
+    return name.includes(q) || name.replace(/\s+/g, '').includes(qn) || key.includes(qn)
+  }).slice(0, 20)
+}
+
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 dsh-tv-player/0.1'
+
+// 频道分组显示名（客户端与 Host 共用语义）。
+export const GROUP_LABELS = {
+  cctv: '央视 CCTV',
+  phoenix: '凤凰卫视 Phoenix',
+  satellite: '卫视 Satellite',
+  other: '其他 Other',
+}
+
+/** 归一化频道显示名：去掉冗余后缀/分辨率标记，便于去重与匹配。 */
+export function normalizeName(name) {
+  return String(name || '')
+    .replace(/\[(?:1080|720|576|480|540)[pP]?\]?/g, '')
+    .replace(/\((?:1080|720|576|480)p\)/gi, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/** 把名称归类到 group。 */
+export function classifyGroup(name, groupTitle) {
+  const g = String(groupTitle || '').trim()
+  const n = String(name || '')
+  if (/凤凰|phoenix|ifeng/i.test(n) || /凤凰|phoenix|港台|香港|台湾/i.test(g)) return 'phoenix'
+  if (/^CCTV[- ]?\d|央视|CGTN|中国教育/i.test(n) || /央视|中央/i.test(g)) return 'cctv'
+  if (/卫视/i.test(n) || /卫视|卫星/i.test(g)) return 'satellite'
+  return 'other'
+}
+
+/** 从名称里抽取画质档位（如「CCTV-1[1080]」「(720p)」「4K」）。 */
+function extractQuality(name, tvgName) {
+  const s = String(name || '') + ' ' + String(tvgName || '')
+  if (/8k/i.test(s)) return '8K'
+  if (/4k/i.test(s)) return '4K'
+  const m = /\[(\d{3,4})[pP]?\]/.exec(s) || /\((\d{3,4})[pP]\)/.exec(s)
+  if (m) return m[1] + 'p'
+  return ''
+}
+
+/** 画质档位 → 数值分（越高越好，用于多源同名频道时保留高画质）。 */
+export function qualityScore(q) {
+  if (/8k/i.test(String(q || ''))) return 432
+  if (/4k/i.test(String(q || ''))) return 216
+  const m = /(\d{3,4})p/.exec(String(q || ''))
+  return m ? parseInt(m[1], 10) / 10 : 0
+}
+
+/** 解析一段 m3u8 文本为归一化频道数组。 */
+export function parseM3u(text) {
+  const out = []
+  let pending = null
+  for (const rawLine of String(text || '').split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (line.startsWith('#EXTINF')) {
+      const mName = /tvg-name="([^"]*)"/i.exec(line)
+      const mLogo = /tvg-logo="([^"]*)"/i.exec(line)
+      const mGroup = /group-title="([^"]*)"/i.exec(line)
+      const mTitle = /,(.*)$/.exec(line)
+      const rawName = (mTitle ? mTitle[1] : (mName ? mName[1] : '')).trim()
+      pending = {
+        name: rawName,
+        tvgName: mName ? mName[1] : '',
+        logo: mLogo ? mLogo[1] : '',
+        groupTitle: mGroup ? mGroup[1] : '',
+      }
+      continue
+    }
+    if (line === '' || line.startsWith('#')) continue
+    if (!pending) continue
+    if (!/^https?:\/\//i.test(line)) { pending = null; continue }
+    // 过滤 IPv6 字面量主机（http://[2409:...]）：多数 IPv4-only 机器不可达，直接跳过。
+    if (/^https?:\/\/\[/i.test(line)) { pending = null; continue }
+    // 过滤 txiptv 的 tsfile/live 中继：这些源用 MP2/AC-3 音轨，浏览器 Chromium 解不了 → 有影无声。
+    if (/\/tsfile\/live\//i.test(line) || /key=txiptv/i.test(line)) { pending = null; continue }
+    const name = normalizeName(pending.name || pending.tvgName)
+    if (name === '') { pending = null; continue }
+    out.push({
+      name,
+      logo: pending.logo,
+      group: classifyGroup(name, pending.groupTitle),
+      url: line,
+      source: 'live',
+      quality: extractQuality(pending.name, pending.tvgName),
+    })
+    pending = null
+  }
+  return out
+}
+
+async function fetchWithTimeout(url, fetchImpl, timeoutMs, signal) {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  const onAbort = () => ctrl.abort()
+  if (signal) {
+    if (signal.aborted) ctrl.abort()
+    else signal.addEventListener('abort', onAbort, { once: true })
+  }
+  try {
+    const r = await fetchImpl(url, { headers: { 'User-Agent': UA }, signal: ctrl.signal, redirect: 'follow' })
+    if (!r.ok) throw new Error('catalog http ' + r.status)
+    return await r.text()
+  } finally {
+    clearTimeout(timer)
+    if (signal) signal.removeEventListener('abort', onAbort)
+  }
+}
+
+/** 频道稳定主键：去掉「卫视/电视/台/频道」等词组、标点与全部空格后的核心名，
+ *  并对央视抽掉类型后缀（综合/新闻/体育赛事…），使「CCTV-1」与「CCTV-1 综合」归并为同一键。
+ *  用作去重键、收藏键与「上次频道」持久化键——跨会话稳定（只要频道名不变）。 */
+export function channelKey(name) {
+  let n = normalizeName(name).replace(/[·\s\-_台频道卫视电视]/g, '').toLowerCase()
+  // 「cctv数字(+)+中文后缀」→ 只保留「cctv数字(+)」；cctv4k/cctv8k 不受影响（k 非中文）。
+  n = n.replace(/^(cctv\d+\+?)[\u4e00-\u9fa5]+$/, '$1')
+  return n
+}
+
+/** EPG 频道匹配键：把频道名归一为与 EPG `<display-name>` 可对齐的核心标识。
+ *  比 channelKey 更激进地抽掉「综合/财经/卫视」等后缀，使「CCTV-1 综合」↔「CCTV1」、
+ *  「CCTV-5+ 体育赛事」↔「CCTV5+」、中文台/资讯台等能对上。 */
+export function epgMatchKey(name) {
+  let n = String(name || '').trim().toLowerCase().replace(/\s+/g, '')
+  const m = /^cctv[-]?(\d+)(\+|plus)?/.exec(n)
+  if (m) return 'cctv' + m[1] + (m[2] ? '+' : '')
+  if (/cgtn/.test(n)) {
+    const lang = n.replace(/^cgtn/, '').replace(/语$/, '').replace(/西班牙/, '西')
+    return 'cgtn' + lang
+  }
+  if (/凤凰/.test(n)) return n.replace(/卫视|台/g, '')
+  if (/卫视/.test(n)) return n.replace(/卫视.*$/, '')
+  return n
+}
+
+/**
+ * 拉取在线目录并与兜底目录合并、去重。每个频道保留**多个候选流 URL**（`urls`，主 URL
+ * 取最高画质），供客户端在某个源失效时自动切换下一源（容灾）。
+ * @param {object} opts { sources, timeoutMs, fetchImpl, signal }
+ * @returns {Promise<{channels: object[], source: string, fetchedAt: number}>}
+ */
+export async function fetchCatalog(opts = {}) {
+  const sources = Array.isArray(opts.sources) && opts.sources.length > 0 ? opts.sources : SOURCES
+  const timeoutMs = opts.timeoutMs || 15000
+  const fetchImpl = opts.fetchImpl || fetch
+  const signal = opts.signal
+  const whitelist = opts.whitelist !== false // 默认应用稳定频道白名单（搜索时传 false 关闭）
+
+  // 先放入精选目录（source: curated，多 URL 起步）；跳过 IPv6 死链与旧 tsfile 中继，
+  // 但保留吉林电信源（222.169.85.8，实测 AAC 可播）。
+  const merged = new Map()
+  for (const c of CURATED_CHANNELS) {
+    const urls = (Array.isArray(c.urls) ? c.urls : [c.url])
+      .filter((u) => typeof u === 'string' && /^https?:\/\//i.test(u))
+      .filter((u) => !/^https?:\/\/\[/i.test(u))
+      .filter((u) => /222\.169\.85\.8/.test(u) || (!/\/tsfile\/live\//i.test(u) && !/key=txiptv/i.test(u)))
+    if (urls.length === 0) continue
+    const key = channelKey(c.name)
+    merged.set(key, { ...c, id: key, source: 'curated', logo: '', quality: c.quality || '', urls, url: urls[0] })
+  }
+  let liveCount = 0
+  const usedSources = []
+
+  // 合并一个实时频道：累积候选 URL（去重、上限 8），主 URL 取最高画质。
+  const mergeLive = (c) => {
+    const key = channelKey(c.name)
+    const existing = merged.get(key)
+    if (!existing) {
+      merged.set(key, { ...c, id: key, source: 'live', urls: [c.url], url: c.url })
+      return true
+    }
+    let urls = Array.isArray(existing.urls) ? existing.urls.slice() : [existing.url]
+    if (!urls.includes(c.url)) urls.push(c.url)
+    if (urls.length > 8) urls = urls.slice(0, 8)
+    const better = qualityScore(c.quality) > qualityScore(existing.quality)
+    merged.set(key, {
+      ...existing,
+      ...c,
+      id: key,
+      source: 'live',
+      name: existing.name, // 保留首个（兜底）更友好的名称
+      urls,
+      url: better ? c.url : existing.url,
+      quality: better ? c.quality : existing.quality,
+    })
+    return false
+  }
+
+  for (const src of sources) {
+    try {
+      const text = await fetchWithTimeout(src, fetchImpl, timeoutMs, signal)
+      const parsed = parseM3u(text)
+      if (parsed.length === 0) continue
+      let added = 0
+      for (const c of parsed) {
+        // 只收录我们关心的三大类（央视/凤凰/卫视），跳过地方台/卡通等噪音。
+        if (c.group === 'other') continue
+        if (mergeLive(c)) added++
+      }
+      liveCount += added
+      usedSources.push(src)
+      if (liveCount >= 400) break // 收录上限，避免超大目录拖慢首次加载
+    } catch {
+      // 单个源失败静默跳过，用剩余源 + 兜底目录。
+    }
+  }
+
+  // 主 URL 排首位，其余候选跟在后面。
+  // 稳定源判定：官方/省级台 CDN（河北台、百视通、浙江台、延边、香港、内蒙古、央视官方）。
+  const stableUrl = (u) => /hebtv\.com|bestv\.cn|cztv\.com|iyb983\.cn|hkstv\.tv|nmtv\.cn|cctvnews\.cctv\.com/i.test(u)
+  const channels = [...merged.values()]
+    .map((c) => {
+      const urls = Array.isArray(c.urls) && c.urls.length > 0 ? c.urls : [c.url]
+      const all = [c.url, ...urls.filter((u) => u !== c.url)]
+      // 稳定源排前面（作主 URL），中继排后面（仅作容灾备份）。
+      const stable = all.filter(stableUrl)
+      const rest = all.filter((u) => !stableUrl(u))
+      return { ...c, urls: [...stable, ...rest], url: stable[0] || all[0] }
+    })
+    // 只保留「确定稳定」频道（白名单），过滤掉间歇性中继（搜索时关闭）。
+    .filter((c) => !whitelist || STABLE_WHITELIST.some((w) => String(c.name || '').includes(w)))
+    .sort((a, b) => {
+      // 卫视排前面（原 6 个卫视在数组最前），央视随后；组内保持数组顺序（稳定排序）。
+      const order = { satellite: 0, cctv: 1, phoenix: 2, other: 3 }
+      return (order[a.group] ?? 4) - (order[b.group] ?? 4)
+    })
+
+  return {
+    channels,
+    source: usedSources.length > 0 ? 'live+' + usedSources.length + ' 源' : '精选频道',
+    fetchedAt: Date.now(),
+  }
+}
+
+/** 按名称/关键词匹配频道：先精确命中，再子串命中。 */
+export function matchChannel(channels, query) {
+  const q = String(query || '').trim().toLowerCase()
+  if (q === '') return null
+  // 关键词归一：把「凤凰」「CCTV13」「cctv 13」「央视13」等变体对齐。
+  const norm = (s) => String(s || '').toLowerCase().replace(/\s+/g, '').replace(/[-·—]/g, '')
+  const qn = norm(q)
+  // 中文频道常见别名（供工具按口语词命中）。
+  const aliases = (ch) => {
+    const n = ch.name
+    const set = [n, norm(n)]
+    const mCctv = /cctv[- ]?(\d+)/i.exec(n)
+    if (mCctv) set.push('cctv' + mCctv[1], '央视' + mCctv[1], '中央' + mCctv[1])
+    if (/凤凰/.test(n)) set.push('凤凰', '凤凰卫视')
+    if (/中文台/.test(n)) set.push('凤凰中文', '凤凰中文台')
+    if (/资讯台/.test(n)) set.push('凤凰资讯', '凤凰资讯台')
+    if (/香港台/.test(n)) set.push('凤凰香港', '凤凰香港台')
+    return set
+  }
+  let best = null
+  let bestScore = 0
+  for (const ch of channels) {
+    for (const a of aliases(ch)) {
+      const an = norm(a)
+      let score = 0
+      if (an === qn) score = 100
+      else if (an.includes(qn) || qn.includes(an)) score = 60
+      else if (a.toLowerCase().includes(q)) score = 40
+      if (score > bestScore) { bestScore = score; best = ch }
+    }
+  }
+  return bestScore >= 40 ? best : null
+}
+
+export default { CURATED_CHANNELS, SOURCES, SEARCH_SOURCES, STABLE_WHITELIST, GROUP_LABELS, normalizeName, classifyGroup, parseM3u, fetchCatalog, matchChannel, channelKey, epgMatchKey, qualityScore, searchChannels }