# HGhub 插件协议(HPP)1.0 · 草案 > 状态:**重构基线草案**。实现按本文档推进;P0 同步产出类型定义、虚构示例与假宿主,验证核心闭环后冻结 1.0。 Windows 开发版的已实现范围、待办与验证命令见 [实现进度](IMPLEMENTATION.md)。 ## 1. 定位 HGhub 是一个**通用视频查看器**:电影、剧集、番剧、综艺、短剧、直播,用同一套界面呈现。 它本身**不包含任何内容来源**——找什么、从哪里取、怎么解析,全部由用户自行导入的 JS 插件提供。 HPP(HGhub Plugin Protocol)定义插件与宿主之间的约定:插件文件长什么样、怎么导入、 在什么环境里运行、能调用什么、要实现什么。 ## 2. 责任边界 - HGhub **不内置、不分发、不审核**任何插件,也不提供官方插件列表。 - 插件是用户自行导入的第三方代码。它访问哪些网站、如何处理用户输入的账号, 由插件作者与使用者自行负责,宿主不做担保。 - 因此协议**不设**签名、审核、权限确认、吊销这类机制。 宿主只承担与自身稳定性相关的事:插件在独立的 JS 引擎里运行,接触不到文件系统和应用内部接口; 插件脚本的死循环与内存超限由宿主中断处理,不阻塞界面与其他插件;不承诺隔离原生引擎自身的进程级故障(见 [03](03-host-rules.md))。 ## 3. 目标 | # | 目标 | 落点 | | --- | --- | --- | | G1 | **核心零内置**:宿主代码、文档、测试中不出现任何上游的域名、接口、密钥、解析逻辑 | 全部 | | G2 | **易于分发**:交付物为单个 `.js` 文件,可直接导入或经列表批量导入,不依赖中心服务 | [01](01-plugin-file.md) | | G3 | **五端运行时一致**:Windows / macOS / Linux / Android / iOS 使用相同的 JS 与宿主 API 语义;媒体解码、可选特性按设备探测 | [02](02-runtime.md)、[09](09-media-transport.md) | | G4 | **结构化的数据**:所有数据有类型、有校验,不用分隔符拼字符串传结构 | [05](05-content-model.md) | | G5 | **能力充分、按需实现**:覆盖影视、短剧与直播的内容获取与播放;界面按能力显隐,允许纯点播源和纯直播源 | [06](06-capabilities.md) | | G6 | **可演进**:协议有版本、有特性探测,新增能力不破坏旧插件 | [07](07-ecosystem.md) | ## 4. 非目标 - **降低插件开发难度**:不以零学习成本或免构建为目标;作者可以使用工程化工具,最终交付单文件即可。接口取舍以能力、语义完整与宿主可维护性为准。 - **DRM**:不涉及 Widevine / FairPlay / PlayReady。 - **插件绘制界面**:插件只返回数据。界面由宿主统一负责。 - **阅读类内容**:漫画、小说不在 1.0 范围内。 - **体验增强类数据源**:弹幕库、字幕库、影视资料库、观看记录同步不在 1.0 范围内。 1.0 只解决"内容从哪里来"。内容源自带的字幕轨属于播放数据,仍在范围内。 - **变现原语**:没有广告位、支付、会员解锁相关的接口。 ## 5. 设计原则 1. **宿主拥有界面,插件拥有数据。** 插件按固定形状返回数据,宿主决定如何呈现;能力缺失时界面自动收起对应入口。 需要用户输入或操作时,插件声明**表单**,宿主渲染在插件页里(见 [06 §15](06-capabilities.md))。 2. **一个文件,一个插件。** 数据源或解析器各自交付为一个自包含 `.js` 文件。 3. **只在被调用时运行。** 插件没有后台;宿主不调用,插件就不执行。 4. **本地优先。** 收藏、历史、进度由宿主本地保存,不登录也能用;云端同步是插件的可选能力。 5. **宽进严出。** 宿主对插件返回的数据做形状校验与容错,单条坏数据不拖垮整页。 ## 6. 架构 ```text 界面(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 插件文件与导入](01-plugin-file.md) | 文件结构、元信息、`manifest.json`、导入与更新 | 草案 | | [02 运行时](02-runtime.md) | 引擎与环境、调用模型、生命周期、错误模型、返回值校验 | 草案 | | [03 宿主规则](03-host-rules.md) | 隔离、网络、限速、隐私 | 草案 | | [04 宿主 API](04-host-api.md) | `hg.*` 各模块的接口 | 草案 | | [05 内容模型](05-content-model.md) | 媒体条目、分集、播放、流、字幕轨的数据形状 | 草案 | | [06 能力模块](06-capabilities.md) | 插件的能力接口与宿主界面映射、聚合搜索与换源 | 草案 | | [07 生态与演进](07-ecosystem.md) | 版本兼容、对标对照、客户端基线与路线图 | 草案 | | [08 宿主界面](08-frontend.md) | 各页面的变更:首页、分类、搜索、插件页、设置页 | 草案 | | [09 媒体传输](09-media-transport.md) | 资源归属、解析器合并、代理、范围请求、刷新与后台播放 | 草案 | ## 9. 关键决策摘要 | 决策 | 选择 | 主要理由 | | --- | --- | --- | | 插件形态 | 单个 `.js` 文件,导出 `meta` 与工厂函数 | 分发与导入不依赖构建环境;元信息结构化,可带设置项 | | 分发 | 直接导入 `.js`,或经 `manifest.json` 批量导入;支持本地文件与 URL | 不依赖任何中心服务;社区自行托管 | | 信任模型 | 不签名、不审核、不设权限确认 | 插件由社区制作、用户自选,宿主不做担保 | | 运行时 | 每插件独立的引擎运行时与执行调度 | JS/API 语义跨端一致;与界面隔离;可设超时与内存上限 | | 宿主接口 | 以参数 `hg` 注入工厂函数 | 作者可在 Node 里用假的 `hg` 做单元测试 | | 网络 | 统一经 `hg.http` | 引擎本身没有网络能力;限速与缓存能统一实现 | | 界面 | 插件只返回数据;需要用户输入时声明表单,由宿主渲染 | 体验一致;维护者专注界面 | | 跨插件协作 | 宿主中转有类型的数据:数据源 → 解析器 | 影视源大量共用同一批视频托管商,解析逻辑值得复用 | | 数据 | 强类型、结构化 | 可诊断、可演进 | ## 10. 规范用语 本协议中的**必须**、**不得**、**应当**、**可以**分别对应 RFC 2119 的 MUST、MUST NOT、SHOULD、MAY。未加粗的同词按日常含义理解。