Orbit v0.2 更新报告

版本定位： 从两个独立的悬浮组件成品，升级为拥有统一入口、统一管理面板和统一交互语言的多 Widget 浏览器 Runtime。

发布范围

本报告以 v0.1.1 发布提交与后续冻结的 v0.2-baseline 为比较边界。仓库没有独立的 v0.2.0 Git tag；变更记录将该系列标记为 0.2.0-c，而 v0.2-baseline 用作 v0.3 开发前的冻结快照。因此，本文以 v0.2 系列能力 而非某个单一 tag 作为汇报对象。

维度	v0.1.x	v0.2 系列	对用户的意义
交付形态	Music、Clock 可独立接入	新增 `dist/orbit.js` 多组件入口	页面只需选择一种集成方式即可获得统一管理
组件管理	无统一面板	Launcher + `Orbit.mount/setVisible/list`	用户能集中显示或隐藏组件
桌面操作	单个组件的既有交互	默认 `Alt+O` 打开管理面板	可快速进入统一控制入口
移动操作	组件自身触控	长按悬浮球打开 Launcher	适配没有键盘的触控设备
文档叙述	FWF 预览与组件并列	统一为 Orbit Runtime	产品模型更清晰

主要更新

v0.2 的决定性更新是新增 src/core/Orbit.js、src/core/Launcher.js、src/entry-orbit.js 以及浏览器产物 dist/orbit.js。原先的 Music 与 Clock 不再只作为孤立脚本存在，而可由 Runtime 注册、启动并在 Launcher 中展示。

对静态站用户而言，推荐接入从“分别引用两个脚本”转变为：引入 Music 与 Clock 的 CSS、写入 window.ORBIT 配置，再引入一个 orbit.js。这降低了多组件接入成本，也为后续增加 Widget 留出了公共入口。

2. Launcher：解决多组件可管理性

Launcher 为桌面提供 Alt+O 快捷键，为移动端提供“长按球体”入口，并加入首次提示与桌面/移动端差异化脚注。其价值不在于弹出层外观，而在于解决了多组件出现后“谁负责统一管理”的产品问题。

v0.2 同时补上了两项关键交互修复：一是 Music 的 display:block !important 场景仍可被隐藏；二是移动端长按松手顺序调整为先识别长按、再结束拖拽，从而避免长按被误判为普通点击。这些修复使 Launcher 的基本操作能在真实页面中成立。

3. 交互与布局向共享语言收敛

新增/调整的 Gesture、Layout、Music CSS 与 Clock Host，使左右吸附、展开方向和移动端卡片边界保持更一致。v0.2 的核心成果并非把所有业务逻辑彻底抽象，而是建立了一个跨 Widget 复用的交互起点：拖拽、吸附、展开、长按、管理入口 使用同一组规则。

验证与发布状态

v0.2 交付了 demo、test-orbit.html、浏览器 IIFE 产物和 API/配置文档；差异范围约为 40 个文件、11,790 行新增、934 行删除。它实现了多组件 Runtime 的主体能力，但该阶段尚无 v0.3 引入的单元测试、产物校验脚本和 GitHub Actions CI。因此，其质量信号主要来自文档化的阶段验收和手动浏览器测试，而非自动化门禁。

兼容性与使用影响

场景	建议
已使用 Music/Clock 单文件	可继续使用独立包；不要与 `orbit.js` 同时引入
新接入多组件页面	使用 `dist/orbit.js`，并保留两份组件 CSS
桌面用户	默认使用 `Alt+O`，可通过 `ORBIT.launcherKey` 改写
移动用户	长按任意球体打开 Launcher；保持手势区域不被页面脚本抢占

风险与下一步

v0.2 的限制主要是 Runtime 仍以“注册 Host + 直接操作 DOM”为主，隐藏、销毁、重挂载的语义没有充分分离；当 PJAX、动态卸载或多个 portal 出现时，资源生命周期容易变得模糊。Music 与 Clock 的复杂度也存在明显差距，未来不宜一次性大改二者。

因此，最合理的下一步正是 v0.3 所采取的方向：先用 Clock 试点建立生命周期契约，再让 Music 接入 destroy、可见性目标和 portal 所有权，而不是在 v0.2 阶段继续堆叠视觉功能。

Orbit-v0.2更新报告