为何没有"逃生舱"

Sentinel 刻意不提供直通 xgplayer 的逃生舱。这是设计决策,不是能力缺失(原始记录见 ADR-025)。

什么是"逃生舱"

很多播放器 SDK 会留一道后门,方便业务方绕过 SDK 直接操作底层内核:

• 透传原始配置 —— 把一整包原生 xgplayer 配置塞进播放器
• 注入自定义插件 —— 往内核里加任意第三方插件
• 交出原生实例 —— 直接把 xgplayer 实例抛给业务代码去 .on() / .play()

Sentinel 这三类都不做。

逃生舱 API(其他 SDK 常见)	Sentinel
透传原始配置 xgplayerConfig	❌ 不提供
注入自定义插件 xgplayerPlugins	❌ 不提供
交出原生实例 onXgplayerReady	❌ 不提供

为什么这是卖点

Sentinel 的核心承诺是契约防漂移:同一份 PlayerConfig 穿过 4 种接入方式——

• React inline(高性能直连)
• React iframe(隔离)
• Vue iframe
• 静态 iframe URL(CMS / Markdown 嵌入)

——行为逐字一致。这由 cross-mode-parity 测试作为硬红线保证。

逃生舱与这条红线正面冲突:一旦任意业务方能塞进任意配置或插件,SDK 就再也无法保证跨接入方式一致,也无法在升级时判断兼容性。

逃生舱换来的"灵活",代价是砍掉整个 SDK 最值钱的一致性保证。我们选择保住一致性。

真需要某个能力怎么办

把它建成一等契约字段,走 ADR 流程——而不是开一个通用透传口。SDK 现有能力大多正是这么长出来的:

• 清晰度切换:不是透传 controls.definition,而是 ready.quality(档位清单)+ setQuality(切换命令)+ qualitychange(结果回报)。业务方用这三件套自建清晰度菜单。
• 字幕 / 弹幕:SDK 暴露轨道 + 切换命令 + 渲染引擎;菜单 UI 归业务团队层。

如果你需要的能力现在没有:提一个 ADR,把它设计成有明确语义、能跨 4 模式一致、能做版本兼容的契约字段。这样新能力天然进入 cross-mode-parity 护栏,而不会成为下一处漂移。

业务 UI 归团队层

覆盖层、清晰度菜单、倒计时这类业务 UI由业务团队用原生 UI 库封装,不在 SDK 内实现,也不需要逃生舱(见 ADR-021)。SDK 只做技术:播放能力、事件、命令、契约、容错。