本文主要介绍一类 Windows 桌面媒体客户端在 UI 路线上的演进：何时用 WebView2 复用主 Web 前端换速度，为何一度把 WinUI 3 写成长期正式方向，以及如何在「两条都重要」时明确当前产品主线，避免文档与开发默认值互相打架。
以 Octans Windows 客户端为例。播放侧早已收敛到受控 LGPL libmpv；真正反复折腾的是管理 UI 用什么壳，以及播放期 OSD 能不能叠在 native 视频上。下面按时间线写清决策关系，不把支线写成已上线事实。
问题域
Windows 客户端通常要同时满足：
| 能力 | 要求 |
|---|---|
| 内容消费 | 海报墙、详情、播放 |
| 库管理 | 高密度列表、批处理、设置 |
| 播放 | native 硬解 / 字幕 / 会话与服务端对齐 |
| 形态 | 键鼠桌面；可选 TV / HTPC 遥控 |
可选架构并不只有「全原生」或「全 Web」：
A. Host + WebView2 加载主 Web UI + native playback
B. 全原生 UI（如 WinUI 3）+ API client + native playback
C. 混合：管理 UI 一套，播放 chrome / OSD 另一套
约束往往来自：重复造业务前端的成本、WebView 与 video HWND 的 airspace / z-order、TV 焦点模型，以及团队能否同时维护两条壳。
阶段一：WebView2 复用主 Web UI（历史）
决策要点
- Desktop 正式 UI 复用已有 Web 前端（路由、鉴权、墙、详情、控制台、设计体系）。
- Windows Host 负责窗口、bridge、日志 / 配置 / 崩溃、native playback、可信 Server origin 加载。
- Host 内嵌的「迷你桌面页」只做 bridge / 认证 / 播放 POC，不扩展成第二套业务前端。
为什么当时合理
主 Web 已有完整管理面与播放页。若在桌面仓再手写墙 / 表 / 弹层，会复制路由、API orchestration、权限与视觉体系，长期成本高于在 Web 侧补 desktop runtime profile 与 Host adapter。
边界（仍值得记住）
- API / Hub 保持同源相对路径；Desktop 直接加载服务端 Web origin，而不是 Host 自带整包 dist。
- 播放接管应发生在播放页 / playback 适配层，不要散落到每个列表页。
- TV / HTPC 不能简单放大桌面管理页；表格、右键、dense toolbar 不是 10-foot 交互。
该路线后来被标为 superseded（被下一阶段文档替代），但作为「最快拿到桌面管理能力」的历史选择仍然成立。
阶段二：WinUI 3 作为长期正式方向（仍有效的候选）
决策要点
长期目标形态写成：
WinUI 3 原生应用
+ 自有设计语言的原生组件库
+ API / 实时客户端
+ LibMpvBackend + 受控 LGPL runtime
+ gpu-next + d3d11 + d3d11va 播放 baseline
不再把「主 WebView2 shell + 整站 Web UI 复用」当作长期 Desktop 主线。Web 继续服务浏览器，并作为能力对照；Windows 共享设计语言、API 与播放契约，不共享页面实现。
为什么要动
| 目标 | Web 复用的压力 |
|---|---|
| 稳定透明悬浮 OSD / 标题栏 | WebView 与 video 层 z-order、命中测试、全屏 / DPI 反复修补 |
| TV / 遥控 | 桌面 Web 信息架构牵制焦点与返回栈 |
| 原生一致性 | Host bridge 成为长期核心协议，复杂度外溢到每个页面 |
明确拒绝的长期主线
- 继续 WebView2 + 主 Web 整站复用作长期主线：短期最快，长期保留多层焦点与输入仲裁。
- Web 主 UI + native 播放 + 透明 Web OSD作长期主线：OSD 合成不能牺牲播放 baseline；且不等于「管理 UI 也应全 Web」。
- 以旧 WPF 业务 UI 为目标框架：既已决定重写业务面，直接面向 WinUI 3 更清晰。
窄范围例外（重要）
拒绝「Web 当主 UI shell」，不等于否定：
原生主应用 + mpv child HWND + 仅播放期的 OSD-only WebView2 / DComp overlay
实测里，同窗口简单叠 XAML OSD 可能出现「OSD 可见视频黑 / 视频可见 OSD 被盖」一类 airspace 问题；独立透明 overlay 路径可在 HDR 样片上验证透出、点击、resize 与退出。这类结论只能服务播放 chrome，不能扩大成 Desktop 管理 UI 复用。
代价
完整管理能力需原生重写；表格虚拟化、弹层、表单 primitives 的迁移量不能低估。若目标只是最快 TV MVP，Web 壳仍是现实捷径；若目标是长期 Windows 产品体验，原生上限更高。
阶段三：明确当前产品主线（运营决策）
长期候选与日常开发 / 发布默认必须拆开。
当前产品主线（以 2026-07 口径）：
main
+ WebView2 / WPF Host
+ Server Web origin 主业务 UI
+ Host bridge / DComp OSD overlay
+ LibMpvBackend + 受控 LGPL runtime
+ portable 发布
| 维度 | 结论 |
|---|---|
| 产品 / 发布主线 | main + WebView2 Host |
| 日常开发默认 | main |
| WinUI 3 | 支线 / 长期候选，不是当前发布主线 |
| 文档默认 | 按 WebView2 写「当前实现」；WinUI 写「候选 / 计划」 |
WinUI 3 决策不撤销，但不得写成「main 已全面原生落地」。若未来把 WinUI 升为产品主线，应新开决策并改写上表。
演进关系一览
WebView2 复用主 Web（历史主线，已 superseded 为「长期方向」）
│
▼
WinUI 3 长期正式方向（候选仍 active）
│
▼
运营拍板：当前发布主线仍是 WebView2 main
│
└── WinUI 支线暂停或按需恢复，不得与 main 写成等价主线
公开表述建议：
- 现在用户装到的：WebView2 Host + 服务端 Web UI + native 播放 + 播放期 overlay。
- 长期仍在评估的：WinUI 3 全原生管理 UI。
- 始终分开的：浏览器 Web ≠ Windows 壳；播放 OSD ≠ 整站 UI。
对同类产品的启示
- 「复用 Web」解决的是管理面速度，不是 TV 与 OSD 免费。TV 仍要独立壳与焦点。
- 长期原生与短期 Web 壳可以并存，但必须写清哪条是发布默认，否则 Agent、文档、CI 会各写各的。
- 播放合成问题单独验收，不要用管理 UI 路线绑架
gpu-next/ 硬解 baseline。 - supersede 要写演进，不要留两份互相打架的「当前真理」。
- LGPL runtime、source offer、可替换链接等边界与 UI 壳无关，换壳时不得回退合规。
注意事项
- 本文是路线与边界说明，不是安装手册，也不承诺 WinUI 交付日期。
- 内部分支名、spike 名仅作演进锚点；对外以「当前主线 / 长期候选」表述即可。
- 具体播放排障见同系列播放文；前端组件库选型见 Web UI 基座文。
相关阅读
- 媒体内容产品 + 管理后台混合前端的 UI 基座选型
- 媒体库播放排障：从会话创建到 HLS / DirectPlay / 字幕链路
- Octans Android 播放内核演进：从 libmpv 单内核到双内核实验
来源
本文综合改写自 Octans 项目 Windows Desktop Web UI 复用决策、WinUI 3 原生 UI 决策，以及 WebView2 产品主线决策。已标注 supersede / 运营主线关系；实现路径已脱敏。