HGhub 插件协议（HPP）1.0 · 草案

状态：重构基线草案。实现按本文档推进；P0 同步产出类型定义、虚构示例与假宿主，验证核心闭环后冻结 1.0。

Windows 开发版的已实现范围、待办与验证命令见实现进度。

1. 定位

HGhub 是一个通用视频查看器：电影、剧集、番剧、综艺、短剧、直播，用同一套界面呈现。它本身不包含任何内容来源——找什么、从哪里取、怎么解析，全部由用户自行导入的 JS 插件提供。

HPP（HGhub Plugin Protocol）定义插件与宿主之间的约定：插件文件长什么样、怎么导入、在什么环境里运行、能调用什么、要实现什么。

2. 责任边界

HGhub 不内置、不分发、不审核任何插件，也不提供官方插件列表。
插件是用户自行导入的第三方代码。它访问哪些网站、如何处理用户输入的账号，由插件作者与使用者自行负责，宿主不做担保。
因此协议不设签名、审核、权限确认、吊销这类机制。

宿主只承担与自身稳定性相关的事：插件在独立的 JS 引擎里运行，接触不到文件系统和应用内部接口；插件脚本的死循环与内存超限由宿主中断处理，不阻塞界面与其他插件；不承诺隔离原生引擎自身的进程级故障（见 03）。

3. 目标

#	目标	落点
G1	核心零内置：宿主代码、文档、测试中不出现任何上游的域名、接口、密钥、解析逻辑	全部
G2	易于分发：交付物为单个 `.js` 文件，可直接导入或经列表批量导入，不依赖中心服务	01
G3	五端运行时一致：Windows / macOS / Linux / Android / iOS 使用相同的 JS 与宿主 API 语义；媒体解码、可选特性按设备探测	02、09
G4	结构化的数据：所有数据有类型、有校验，不用分隔符拼字符串传结构	05
G5	能力充分、按需实现：覆盖影视、短剧与直播的内容获取与播放；界面按能力显隐，允许纯点播源和纯直播源	06
G6	可演进：协议有版本、有特性探测，新增能力不破坏旧插件	07

4. 非目标

降低插件开发难度：不以零学习成本或免构建为目标；作者可以使用工程化工具，最终交付单文件即可。接口取舍以能力、语义完整与宿主可维护性为准。
DRM：不涉及 Widevine / FairPlay / PlayReady。
插件绘制界面：插件只返回数据。界面由宿主统一负责。
阅读类内容：漫画、小说不在 1.0 范围内。
体验增强类数据源：弹幕库、字幕库、影视资料库、观看记录同步不在 1.0 范围内。 1.0 只解决"内容从哪里来"。内容源自带的字幕轨属于播放数据，仍在范围内。
变现原语：没有广告位、支付、会员解锁相关的接口。

5. 设计原则

宿主拥有界面，插件拥有数据。 插件按固定形状返回数据，宿主决定如何呈现；能力缺失时界面自动收起对应入口。需要用户输入或操作时，插件声明表单，宿主渲染在插件页里（见 06 §15）。
一个文件，一个插件。 数据源或解析器各自交付为一个自包含 .js 文件。
只在被调用时运行。 插件没有后台；宿主不调用，插件就不执行。
本地优先。 收藏、历史、进度由宿主本地保存，不登录也能用；云端同步是插件的可选能力。
宽进严出。 宿主对插件返回的数据做形状校验与容错，单条坏数据不拖垮整页。

6. 架构

界面（WebView）
  React：首页 / 分类 / 搜索 / 详情 / 播放器 / 片库 / 插件管理
  不含任何数据源知识
      │ IPC：通用命令（plugin_call、library_*、settings_* …）
      │ 本地媒体会话地址（应用协议或本地 HTTP，按平台实现）
      ▼
宿主核心（Rust）
  ├─ 插件管理器     导入 · 初始化/能力发现 · 更新检查 · 启停 · 移除
  ├─ 调用调度器     返回值校验 · 超时 · 取消
  ├─ 插件运行时     每插件独立运行时、内存预算与执行调度，通过 hg.* 与宿主交互
  ├─ 网络层         HTTP 客户端 · Cookie · 限速 · 缓存
  ├─ 媒体会话与代理  资源归属 · 解析链 · HLS 改写 · Range · 刷新 · 字节变换
  └─ 存储           插件键值存储 · 本地片库
      ▼
上游站点与 CDN

7. 术语

术语	含义
宿主	HGhub 应用本身，协议的实现方
插件	一个 `.js` 文件，对应一个数据源或解析器
插件列表	一个 `manifest.json`，列出若干插件文件，用于批量导入
能力	插件实现的一组相关方法，如 `search`、`comments`
特性	宿主的可选功能，插件可探测，如 `webview`
可传递值	能在宿主与插件之间传递的值：JSON 值与 `Uint8Array`
媒体会话	宿主管理的资源引用、提供者、请求环境及播放刷新信息，不是插件后台任务

中文里"线路"一词有三种不同含义，本协议分别命名，不混用：

本协议用语	英文	含义
站点线路	endpoint	同一上游的不同入口域名（主站、备用站、镜像）
播放列表	playlist	同一部作品的多套分集列表（不同片源、配音、正片/花絮）
播放线路	server	同一集的多个取流服务器

8. 文档地图

文档	内容	状态
01 插件文件与导入	文件结构、元信息、`manifest.json`、导入与更新	草案
02 运行时	引擎与环境、调用模型、生命周期、错误模型、返回值校验	草案
03 宿主规则	隔离、网络、限速、隐私	草案
04 宿主 API	`hg.*` 各模块的接口	草案
05 内容模型	媒体条目、分集、播放、流、字幕轨的数据形状	草案
06 能力模块	插件的能力接口与宿主界面映射、聚合搜索与换源	草案
07 生态与演进	版本兼容、对标对照、客户端基线与路线图	草案
08 宿主界面	各页面的变更：首页、分类、搜索、插件页、设置页	草案
09 媒体传输	资源归属、解析器合并、代理、范围请求、刷新与后台播放	草案

9. 关键决策摘要

决策	选择	主要理由
插件形态	单个 `.js` 文件，导出 `meta` 与工厂函数	分发与导入不依赖构建环境；元信息结构化，可带设置项
分发	直接导入 `.js`，或经 `manifest.json` 批量导入；支持本地文件与 URL	不依赖任何中心服务；社区自行托管
信任模型	不签名、不审核、不设权限确认	插件由社区制作、用户自选，宿主不做担保
运行时	每插件独立的引擎运行时与执行调度	JS/API 语义跨端一致；与界面隔离；可设超时与内存上限
宿主接口	以参数 `hg` 注入工厂函数	作者可在 Node 里用假的 `hg` 做单元测试
网络	统一经 `hg.http`	引擎本身没有网络能力；限速与缓存能统一实现
界面	插件只返回数据；需要用户输入时声明表单，由宿主渲染	体验一致；维护者专注界面
跨插件协作	宿主中转有类型的数据：数据源 → 解析器	影视源大量共用同一批视频托管商，解析逻辑值得复用
数据	强类型、结构化	可诊断、可演进

10. 规范用语

本协议中的必须、不得、应当、可以分别对应 RFC 2119 的 MUST、MUST NOT、SHOULD、MAY。未加粗的同词按日常含义理解。