Niskle Link 互联方案（头显端）

本文是三份文档中的头显端实现方案。协议只在 01-互联协议规范-v1.md 里定义，本文不重复定义协议，只描述 Link 侧如何实现它。文中「协议 §N」均指该文档。

• 目标版本：Link 1.9.0（当前 app/build.gradle.kts:19-20 = versionCode 162 / 1.8.1）

• 对应协议阶段：P4–P7（协议 §13）　编写日期：2026-09-15　状态：设计定稿，尚未实现

• --

1. 目标与非目标

1.1 目标

1.2 非目标

---

2. 整体架构

2.1 包结构（新增 app/src/main/java/com/framecast/stream/remote/）

remote/ 不 import service. 或 ui.，唯一例外见 §2.3。

2.2 数据流

┌──────────────────────── Compose 层（ui/remote/）────────────────────────┐
│ LinkScreen ─┬─ ConnectPage  配对码 / 手动 IP / 发现的 PC 列表            │
│             ├─ OverviewPage 状态 + 快捷开关                              │
│             ├─ FacePage     面捕参数                                     │
│             ├─ BodyPage     设备列表 / 部位分配 / 校准 / 自动测量         │
│             └─ UpdatePage   更新 + 已配对设备管理                        │
│                    │                                                     │
│        RemoteToastHost ◄── Flow<RemoteNotice>（面板内 toast，绝不静默）   │
└────────────────────┬─────────────────────────────────────────────────────┘
                     │ StateFlow<RemoteUiState> / 事件回调
┌────────────────────▼─────────────────────────────────────────────────────┐
│ RemoteViewModel (AndroidViewModel) —— 无业务逻辑                          │
└────────────────────┬─────────────────────────────────────────────────────┘
┌────────────────────▼─────────────────────────────────────────────────────┐
│ RemoteRepository —— 连接状态机（§3）                                      │
│   ├─ 能力清单缓存 Map<op, HubOperation> ──► CapabilityGate                │
│   └─ 令牌（内存态；磁盘态由 RemoteTokenStore 加密保存）                    │
└──┬──────────────────┬───────────────────────┬────────────────────────────┘
┌──▼───────────────┐ ┌▼────────────────────┐ ┌▼───────────────────────────┐
│ RemoteClient     │ │ EventStream (SSE)   │ │ RemoteDiscovery            │
│ HttpURLConnection│ │ BufferedReader      │ │ 1 记住的端点               │
│ 2s / 5s 超时     │ │ 退避 1→2→4…30s      │ │ 2 MjpegPeerHint(入站源地址)│
│ 请求 id 关联     │ │ 服务端 retry 覆盖   │ │ 3 BeaconListener(UDP 37022)│
│ busy→按 retry    │ │ status/notice 分发  │ │ 4 手动 IP                  │
└──────────────────┘ └─────────────────────┘ └──────┬─────────────────────┘
                                                    │ 只读
                                        ┌───────────▼─────────────────────┐
                                        │ MjpegHttpServer（既有，:18980） │
                                        └─────────────────────────────────┘

2.3 与既有 StreamService 的关系：互不依赖

StreamService 用静态 companion flow 发布状态、onBind 返回 null（StreamService.kt:111），没有 binder、没有第三个进程内服务位。

• 不新增前台服务：控制 PC 的场景就是用户正看着 LINK 面板的时候，面板不可见时保持 SSE 也没有意义（没人看 toast）。新开 FGS 还要与 StreamService 的 foregroundServiceType="camera|connectedDevice"（AndroidManifest.xml:98）争抢类型与 startForeground 路径（StreamService.kt:498-525），风险大于收益。

• RemoteHub 是 FrameCastApp 持有的 app 单例（照抄 FrameCastApp.kt:14-39 持 preferences/instance 的既有模式，零新概念）。

• 唯一接触点：MjpegHttpServer.handleClient(socket)（:94）记录 socket.inetAddress.hostAddress 到 MjpegPeerHint。单向、可空、可失败；remote/ 不 import service.，耦合面 1 行。

• --

3. 连接状态机

3.1 状态与 UI

unknown_op 不改变连接状态（协议 §4.4 硬规则）：只让 CapabilityGate 把对应控件置灰，行内显示「PC 端版本过旧」。

3.2 关键迁移

3.3 三种典型故障的确定行为

---

4. 发现实现

按协议 §10.2 的四级优先级，前一步成功即停止。

4.1 第 1 级：记住的上次成功端点

持久化 remote_last_endpoint（192.168.1.10:21120）。冷启动先 GET /v1/info 探测，2 秒超时；失败降级到第 2 级，该键先留着不删（PC 可能只是还没开机完）。

4.2 第 2 级：从既有入站 MJPEG 连接学习 PC IP（零新增机制）

PC 端 Engine 会主动连接 Link 的 MJPEG 服务器（mjpeg_http_client.cpp:171-174），Link 因此天然知道 PC 的源地址：

1. 在 MjpegHttpServer.handleClient(socket)（MjpegHttpServer.kt:94）把 socket.inetAddress.hostAddress 写入 MjpegPeerHint（带时间戳），只接受通过协议 §10.1 安全 IPv4 校验的地址。

2. 发现流程读该 hint，配 21120 做 /v1/info 探测。

3. StreamService 未运行、hint 为空时直接跳过。

在已经推流的正常场景下这一条几乎总是第一个命中，完全不需要广播；代价是 1 行写入。

4.3 第 3 级：监听 Hub 信标（UDP 37022）

LanDiscovery 是只发不收：registerService（LanDiscovery.kt:137-160）、DatagramSocket 只 send（:171-174,205-207），没有 discoverServices、没有 ResolveListener、没有接收线程。接收侧由新建的 BeaconListener 承担：

4.4 MulticastLock：需要，但只在有限窗口持有

CHANGE_WIFI_MULTICAST_STATE 已在 AndroidManifest.xml:21 声明却从未使用。现代 AP 广播抑制与 Android Wi-Fi 省电会按接口丢弃广播帧，Pico Neo3 在息屏/省电档尤其明显——不持锁时「时好时坏」是最难排查的现场问题。但长持锁显著增加功耗，因此窗口定得很窄：只在发现流程进行中且 LINK 面板可见时 createMulticastLock("niskle-link-discovery")，最长 30 秒或首个 peer 到达即释放；acquire()/release() 严格配对，在 finally 里释放。

4.5 第 4 级：手动 IP（VR 里必须好用）

• 入口自动浮现：搜索 10 秒无结果即显示，不藏在设置里。

• LiquidTextField（LiquidControls.kt:967）+ KeyboardOptions(keyboardType = KeyboardType.Number)。头显数字键盘没有 .，因此输入目标不是完整 IPv4，二选一：① 默认只输最后一段（用 NetworkSnapshot 推本机前缀如 192.168.1.，只输 10，覆盖 95% 同网段场景）；② 完整 IPv4，用 KeyboardType.Uri，作为「高级」开关。

• 端口默认 21120，折叠在「高级」里，同样只允许数字。

• 输满即自动探测 /v1/info，用 LiquidProgressIndicator（:1185）显示进度；失败用字段的 isError + supportingText 报错，成功写入 remote_last_endpoint。

• --

5. 配对流程 UI

5.1 用户看到什么

1. PC 端在 Hub 设置页点「配对新设备」→ Hub 窗口显示 6 位大字号数字码，TTL 120 秒（协议 §5.3）。

2. 头显进入 待配对：标题「在 PC 上点击『配对新设备』」+ 六格大号输入框（RemotePinField，§8.3），每格触摸目标 ≥ 64dp。

3. 输满 6 位按钮自动点亮（LiquidActionButton 的 loading，LiquidControls.kt:250）。

4. 成功 → 连接中 → 已连接 + toast「已连接到 DESKTOP-ABC」；失败 → 清空输入，toast 显示服务端 message（协议 §4.3 要求它是可直接展示的中文）。

5.2 错误处理

5.3 令牌去向

token（32 字节 base64url）与 client_id 都不进普通持久化，只经 RemoteTokenStore 用 Keystore AES-GCM 包一层后落盘（§11.2）。内存态只存在 RemoteRepository 的私有字段；RemoteClient 只从参数接收令牌，异常信息里也不拼接令牌。

5.4 后续改进（本阶段不做）

App 已声明 horizonos.permission.HEADSET_CAMERA 与相机 feature（AndroidManifest.xml:11-13,37），Pico/Quest 均允许相机访问，因此用头显摄像头扫 PC 屏幕上的二维码是可行的下一步：Hub 把 {instance_id, ip, port, 一次性 pair_code} 编成二维码，扫码即完成发现 + 配对，把 §4 与 §5 压成一步。本次仅备案。

---

6. HTTP 客户端

6.1 为什么仍是 HttpURLConnection 且不需要新依赖

• 全仓库唯一客户端是 update/UpdateRepository.kt（217 行，HttpURLConnection 见 :8,28,106），焊死在 OTA 语义上：15s/60s 超时（UpdateConfig.kt:29-30）不可按调用覆盖、无取消。UpdateRepository 不复用——对休眠中的 PC 发一次「开始追踪」会卡 UI 15–60 秒。

• 协议只有 6 个端点、请求/响应模型、JSON 体 ≤64 KiB、下行走 SSE。这种规模下 OkHttp/Retrofit 的连接池/拦截器/类型安全收益都不成立，代价却是新依赖 + 混淆规则 + 体积。

• isMinifyEnabled=true/isShrinkResources=true（app/build.gradle.kts:42-43）且 proguard-rules.pro 只保护 UVC/JNI（:1-16），任何反射式序列化库都要额外 keep 规则，漏一条就是 release-only 崩溃。org.json 是平台内置、无反射、无 keep 需求。

• settings.gradle.kts:1-18 未声明任何序列化插件——这本身就是引入新依赖不划算的信号。

• *结论：org.json + HttpURLConnection，零新依赖**，与 UpdateInfo.fromJson（UpdateInfo.kt:52-60）的手写风格一致。

6.2 客户端要求

6.3 错误映射（封闭集合）

RemoteError 与协议 §4.4 一一对应：BadRequest/UnsupportedVersion/Unauthorized/Forbidden/UnknownOp/InvalidArgs(field)/Busy(retryAfterMs)/Unavailable/Timeout/Internal。

• 4xx/5xx 能解析出 error.code → 用 code（HTTP 状态码只做校验，不参与判定，避免两端状态码表漂移）。

• 未知 code → Internal（协议 §11.1：未知错误码当 internal）。

• 非 2xx 且响应体不是 JSON（中间设备插了 HTML 页）→ Internal，message 用「PC 端返回了无法解析的响应」。

• 连接/读取超时 → Timeout；连接被拒 / host unreachable → Unavailable。二者区分开，否则给不出「Hub 未启动」这种有用的提示。

6.4 busy 自动重试

busy（409，协议 §7.2 的资源组串行化）是预期内的正常返回：按钮进 loading → 等 retry_after_ms（缺省 500ms、上限 3000ms，协议 §4.3）→ 自动重试最多一次 → 仍失败则停止自动重试，把按钮恢复为可手动重试并 toast 服务端 message（如「体感追踪正在启动」），不进入循环；用户离开页面或点取消 → Job.cancel() 立即终止。

为什么只自动重试一次而不是三次：协议 §7.2 的串行化是「不排队、立刻返回 busy」。 如果客户端连续重试三次，在 PC 端看起来就是一次操作被重放三次，而 Engine 命令队列溢出时会丢弃最旧 ——重试反而可能挤掉桌面用户自己的操作。一次重试是「等对方忙完」，多次重试就是「抢」。

6.5 两个具体坑

1. connectTimeout/readTimeout 是实例属性，不是全局设置。 每个新建的 HttpURLConnection 都要显式赋值（参照 UpdateRepository.kt:29-30,107-108）；漏设就拿不到 2s/5s，退回平台默认（读超时 0 = 无限等待）。因此「建连 + 设超时 + 设头」收敛到一个私有函数，openConnection() 全项目只有这一处。

2. 连接池是 per-JVM 的且行为受限。 复用依赖 keep-alive 与响应体被读完；协议要求服务端设 Connection: close 或正确 Content-Length（协议 §3），因此实际上每次请求都会新建 TCP 连接。局域网可接受（RTT < 2ms），但不能假设「热连接更快」，也不要基于连接复用做限流设计。响应体读完并 finally { conn.disconnect() }（照抄 UpdateRepository.kt:50,206）。

---

7. SSE 客户端

7.1 读取循环

GET /v1/events?topics=status,notice&hz=2，Accept: text/event-stream。用 BufferedReader(InputStreamReader(conn.inputStream, UTF_8)) 逐行 readLine()：

readTimeout 设 40 秒（服务端心跳 15 秒，允许丢 2 次）。这个值是有作用的：若服务端进程被挂起而非断开，没有读超时读取线程会永久阻塞，重连永不触发。status 的 data 用 org.json 解析成 RemoteStatus（未知字段忽略），notice 解析成 {level, text, sticky}。

7.2 重连退避

• 默认 1→2→4→8→16→30 秒（上限 30s），带 ±20% 抖动避免多头显同时重连。

• 收到过服务端 retry: 时用它作基数再乘退避倍数，仍钳制 1000–30000 ms。

• 连接稳定 10 秒后退避计数归零。

• 断线语义遵循协议 §8.2：只显示「连接中断」，不清除已配对状态。

• 重连成功后重拉 GET /v1/capabilities（PC 可能刚更新过）。

7.3 屏幕不可见时是否保活

结论：不保活，但保留快速重连能力。

• 面板不可见（Lifecycle < STARTED）→ 断开 SSE，转低频探测（每 30 秒一次 GET /v1/info，2 秒超时）。

• 面板重新可见 → 立即重连并拉一次 capabilities（预期 < 500ms，用户无感）。

• 理由：① 看不到 toast 时接收 notice 毫无价值；② 头显电池与 Wi-Fi 唤醒预算宝贵，且同进程 StreamService 已在做 UVC 采集与 YUV→JPEG；③ 协议 §8.2 明确「断线不改变配对状态」，断开是安全的。

• 唯一例外：用户正在观察长操作（body.autobone、update.install）时，页面切走也保留 SSE，直到该操作结束或 5 分钟超时。

• --

8. 屏幕与交互

8.1 页面清单（手写 Compose，映射协议 §12.1 分组）

confirm: true 的操作（vrcft.stop、body.start、body.stop、body.autobone、capture.clear、update.install、client.revoke）一律用 Link 自己的确认弹层，文案逐字照抄协议 §9.4——用户看不到 PC 屏幕，文字必须说明后果。

8.2 VR 可用性规则（硬性）

1. 触摸目标 ≥ 56dp，主操作 ≥ 64dp 高（头显手势/手柄射线落点精度远低于手指）。

2. 不做密集文本：每卡片最多 3 行，正文 ≥ 15sp，数字用大字号独立块。

3. 除数字外不用打字：枚举一律用选择器，只有配对码、IP、设备重命名会唤起键盘。

4. 破坏性操作一律在 App 内二次确认，不用系统 Toast 承担确认职责。

5. 每个错误都以面板内 toast 呈现，没有静默失败。 唯一例外是 SSE 断开（只改徽章：它会自动恢复且会连续发生）。任何 catch 里既无 toast 也无状态变更，都算 bug。

8.3 先建的缺失组件

现有设计系统没有列表/LazyColumn、下拉选择、Snackbar/Toast、连接状态组件，且 LiquidModal 是 private（HomeScreen.kt:2017）。建设顺序按下表：

8.4 视觉预期

supportsOpticalGlass 是 Build.VERSION.SDK_INT >= TIRAMISU（HomeScreen.kt:201、LiquidGlass.kt:134）。Pico Neo3 是 Android 10（API 29），远低于 33，因此目标设备上「液态玻璃」会退化到 LiquidGlass.kt:287-304 的平面分支：纯色 tint + 阴影 + 边框。这不是 bug，是既有行为。本次不承诺任何视觉打磨：不靠模糊区分层级，不把关键信息藏在玻璃层后面；验收只看「API 29 上信息清晰、可点、状态可读」。

---

9. 通知（notice → 面板内 toast）

链路：SSE event: notice → RemoteRepository → Flow<RemoteNotice> → RemoteToastHost。协议 §8.3 的 notice 是头显场景价值最高的主题。

status 变化驱动的本地提示（如「追踪已启动」）也走同一队列，保证用户操作总有反馈。

---

10. 导航改造

10.1 现状为什么不可扩展

NiskleTab 只有两个成员（LiquidGlass.kt:102）。加第三个 Tab 要改 7 处硬编码：枚举本身、selectedIndex = if (selected == STREAM) 0 else 1（LiquidBottomTabs.kt:373）、if (index == 0) … else …（:382）、tabsCount = 2 与固定 Modifier.width(220.dp)（:386-387）、两个字面量 Tab 块（:390-434）、when(tab)（HomeScreen.kt:270-341）、按 ordinal 排序的 AnimatedContent（:366）。而 HomeScreen.kt 已 2503 行，HomeScreen(...) 已吃 18 个状态值 + 19 个回调（:154-196）。

10.2 改造三步（每步独立可编译）

HomeScreen 的 37 个参数本身就是下一个技术债。本次不做全面重构（无测试保护，见 §12），但边界要守住：remote 相关回调不再往 HomeScreen 里塞。

10.3 顶层 Tab 还是设置子页

结论：顶层 Tab（第 3 个）。

1. 需要常驻状态可见性：用户随时都想知道「PC 还连着吗」。放进设置二级页等于把这信息藏两层，而 ConnectionBadge 的价值就在常驻。

2. 操作频次：戴着头显操作 PC 是高频核心动作，「设置 → 找入口 → 进入」在 VR 里是 3 倍操作成本。

3. ordinal 动画天然支持：AnimatedContent 用 targetState.ordinal 判方向（HomeScreen.kt:366），列表顺序天然给出 ordinal，无需改动画代码。

代价是底部栏由 220dp 变宽到约 330dp，在 Pico Neo3 的 2D 面板里仍居中可点。SettingsPage 那套 private enum 保持不动（HomeScreen.kt:151），LINK 内部子页照抄同样的 rememberSaveable + enum 模式（:212-213），不引入 navigation-compose——为 5 个子页引入导航库不值得，且会与既有返回键处理（:262-267）打架。

---

11. 持久化与安全

11.1 新增 DataStore 键

文件仍是 framecast_settings_v2（PreferencesRepository.kt:19），键加在 private object Keys（:71-87，现 15 个键）。

硬规则：新键只提供 Flow 与 suspend fun set…()，不再新增 …Sync() getter。既有 runBlocking { dataStore.data.first() }（:169-171,173-175,197-203）被主线程 1Hz 与逐帧调用（StreamService.kt:50,225-232,415）是既有反模式；本次不改它（无测试保护），但新代码不复制这套写法，RemotePrefs 全部挂起。

11.2 令牌保护决策

事实：android:allowBackup="true" + dataExtractionRules/fullBackupContent（AndroidManifest.xml:51-53）。现有规则只 include domain="sharedpref"（backup_rules.xml:3、data_extraction_rules.xml:4,7），不含 file 域，所以 DataStore 的 framecast_settings_v2.preferences_pb 目前不在备份范围内——但这是巧合而非设计，且 adb backup、root、云备份策略变更都可能打破它。真正的现实风险是 AppLog/LogExporter/CrashHandler（§11.3）。

选定方案：Keystore AES-GCM 信封加密后再落入 DataStore。

实现要点：

1. 别名 niskle_link_hub_token_v1，KeyGenParameterSpec 用 AES/GCM/NoPadding、setUserAuthenticationRequired(false)、setRandomizedEncryptionRequired(true)。

2. 信封结构（避免每次请求走 Keystore 慢路径，也便于轮换）：随机 32 字节 DEK → 用 DEK 加密 token（随机 12 字节 IV，128-bit tag）→ 用 Keystore 的 KEK 加密 DEK（同样随机 12 字节 IV）→ 存 base64([1B 版本][12B wrapIV][wrapCt][12B dataIV][dataCt])。

3. IV 处理：IV 每次都从 SecureRandom 取新的 12 字节，重用一次都不行；GCM 下 IV 重用是灾难性错误。IV 需要保证的是唯一性而非保密性，明文拼接存储是正确的。

4. 密钥失效：KeyPermanentlyInvalidatedException、UserNotAuthenticatedException、AEADBadTagException、解密后校验失败，全部走同一条路径——清 remote_token_sealed + remote_client_id → 待配对 → toast「配对信息已失效，请重新配对」。不做「先试试无令牌请求」的模糊降级，那只会让用户看到一堆 unauthorized 却不知发生了什么。

5. 解密入口唯一：只有 RemoteTokenStore 能产出明文 token；明文只以参数形式在进程内传递，不进任何 data class 的 toString。

11.3 日志不泄露令牌与配对码

AppLog（AppLog.kt:23-41）既 Log.x 到 logcat 又写入内存环形缓冲；LogExporter.exportToDownloads 把 AppLog.dumpAll()（LogExporter.kt:97）写到公共 Downloads 目录（:26-31）；CrashHandler 闪退时把同一份缓冲写到应用私有目录 + Downloads（:37-53）；:148-165 的兜底路径还会写 getExternalFilesDir，部分设备上可被文件管理器读到。措施：

1. RemoteLogScrubber.scrub(s)：正则替换 (?i)(token|authorization|bearer|pair_code|secret)\s*[:=]\s*\S+ → $1=***，并对疑似 base64url 的长串整体打码。

2. remote 日志全部过 scrubber；RemoteClient/RemoteTokenStore/SSE 解析层不直接调 AppLog。

3. 配对码只存在于配对页 Composable 局部状态与单次请求体，不进 Repository、不进持久化、不进日志。

4. 新增自检：debug 构建导出日志前断言 dumpAll() 不含任何已注册敏感串，把「有没有泄露」变成可回归的测试。

5. 顺带建议（属 PC 端范畴）：network_security_config.xml:3 是裸的 cleartextTrafficPermitted="true"，将来若要收窄头显端明文范围，做法是改成 domain-config 白名单。

---

12. 风险与未决问题

12.1 协议修订项（已全部采纳并写入协议规范）

编写本文时针对协议规范 v1 提出了 7 条修订意见，均已采纳，下表是它们的落地位置。 实现时以协议规范为准，本节仅作追溯。

另外协议还新增了两节与本文强相关：§0.1 / §15（控制面与未来串流媒体面的解耦要求）。 Link 将来要承载串流，因此 §15.2 的分层要求同样约束本文的 remote/ 包 ——remote/ 里的纯逻辑部分不依赖 Android 框架，以便将来头显端的媒体面复用它。

---

13. 分阶段实施（对齐协议 §13 的 P4–P7）

每阶段收尾的固定动作：① .\gradlew.bat assembleDebug 通过；② .\gradlew.bat testDebugUnitTest 通过；③ 真机 Pico Neo3 按上表手工验证并留截图/日志；④ 全程不执行任何 git 写命令（仓库无历史，git checkout/reset/commit 都可能造成不可逆损失）。

---

14. AI 实现提示词（P4 + P5）

把下面整段交给一个在 D:\Work\Niskle-Link 里工作的 AI 编码代理。先只读代码，再改代码。

你在 D:\Work\Niskle-Link（Niskle Link，Android 头显端 App）里实现「远程控制 PC 端 Niskle Hub」的头显侧客户端。

一、必读（只读，不要改）
1. C:\Users\Administrator\Desktop\Niskle互联方案\01-互联协议规范-v1.md —— 唯一协议真相源，不要自己重新定义协议。
2. 先完整读这些文件再动手：
   app/src/main/java/com/framecast/stream/update/{UpdateRepository,UpdateConfig,UpdateInfo}.kt
   app/src/main/java/com/framecast/stream/data/PreferencesRepository.kt
   app/src/main/java/com/framecast/stream/ui/screens/{HomeScreen,LiquidGlass,LiquidControls,LiquidBottomTabs}.kt
   app/src/main/java/com/framecast/stream/FrameCastApp.kt
   app/src/main/AndroidManifest.xml、app/build.gradle.kts、settings.gradle.kts

二、技术栈与硬约束（违反即返工）
- Kotlin + Jetpack Compose + Gradle KTS，package com.framecast.stream，minSdk 24 / targetSdk 34。
- 【禁止新增任何第三方依赖】。JSON 一律用平台自带的 org.json 手写解析（参考 UpdateInfo.fromJson）。不要引入 Retrofit/OkHttp/Gson/Moshi/kotlinx-serialization/Ktor。
- 【禁止复用 UpdateRepository】。它的超时是 15s/60s 且不可覆盖（UpdateConfig.kt:29-30），会对休眠中的 PC 卡死 UI。新写一个客户端：连接超时 2s、读取超时 5s，每次调用可覆盖；每个 HttpURLConnection 实例都必须显式设置 connectTimeout/readTimeout，并 finally { disconnect() }。
- 【持久化只用挂起函数】。绝对不要写 runBlocking，也不要新增任何 …Sync() getter（PreferencesRepository.kt:169-203 的 runBlocking 是既有反模式，不要复制）。
- 令牌不能明文落盘：用 javax.crypto + android.security.keystore 做 AES-GCM 信封加密后再存进 DataStore（framecast_settings_v2）。令牌与配对码绝不进 AppLog/日志/异常 message（AppLog 会被 LogExporter 导出到公共 Downloads 目录）。
- 设计系统组件都是 internal（模块内可见，可直接用）：ContentGroup、LiquidGlassSurface、StandardActionButton、StandardSwitch、StandardSlider、ProgressiveBlurHeader、LiquidButton、LiquidActionButton（有 loading 参数）、LiquidTextField、LiquidChoiceField、LiquidNavRow、LiquidSegmentButton、LiquidProgressIndicator。缺少列表/下拉/Toast/对话框组件，需要自己建；LiquidModal 在 HomeScreen.kt:2017 是 private，把它提升为 internal，不要复制一份。
- 新增包 com.framecast.stream.remote（纯逻辑，其中不依赖 Android 框架的部分要能跑单元测试）与 com.framecast.stream.ui.remote（Compose）。
- 新建 app/src/test 单元测试源集，至少覆盖：发现优先级排序、peer 表按 instance_id 去重与 6 秒过期、请求/响应信封编解码、错误码→RemoteError 映射、令牌加解密往返、能力门控（op 不存在或 since>1 → 置灰）。

三、本次范围（只做 P4 + P5）
P4：发现（按协议 §10.2 四级优先级：记住的端点 → 从 MjpegHttpServer 入站连接学习 PC 的 IP → 监听 UDP 37022 信标 → 手动 IP）、配对界面（6 位数字码）、连接状态机（未配置/搜索中/待配对/配对中/连接中/已连接/降级/连接中断）、总览状态页。
P5：追踪与面捕控制页、SSE 客户端（status + notice）、面板内 toast 通知队列（去重 + 限流）。
另外：把底部导航栏改造成数据驱动（NiskleTab → data class 列表，去掉 tabsCount=2、selectedIndex 的 if-else、Modifier.width(220.dp) 这些硬编码），并新增一个 LINK 顶层 Tab。
不做：体感追踪页（P6）、更新页（P7）、QR 扫码、云端中继、任何 XR SDK。

四、语义规则
- unknown_op 绝不断连：只把对应控件置灰并提示「PC 端版本过旧」。
- unauthorized：清除本地令牌与 client_id，回到配对流程。
- busy：按 retry_after_ms 自动重试，**最多一次**（缺省 500ms，上限 3000ms，见协议 §4.3）；仍失败则把按钮置为可手动重试并提示，不允许无限自动重试。
- SSE 断开只显示「连接中断」，不改配对状态；退避 1→2→4→8→16→30 秒，服务端 retry: 优先。
- 所有错误必须在面板内 toast 显示服务端返回的中文 message，不允许静默失败（唯一例外：SSE 断开只改状态徽章）。
- 配对码/IP 输入只允许数字键盘；触摸目标 ≥ 56dp；破坏性操作必须用 App 内确认弹层。

五、验证与汇报（必须做）
1. 运行 .\gradlew.bat assembleDebug（JDK 17、Android SDK 34），把完整结果如实报告（成功或错误原文）。
2. 运行 .\gradlew.bat testDebugUnitTest，报告通过情况。
3. 明确列出「哪些结论在没有真机 Pico Neo3 的情况下无法验证」，至少包括：UDP 广播在实际 AP 下能否收到、MulticastLock 是否必要、系统键盘是否遮挡配对输入框、与实际 Hub 的端到端联调（Hub 端 API 目前尚不存在，只能对 mock 验证）。
4. 不要执行任何 git 写命令（该仓库没有任何提交历史）。
5. 不要改动 package name、versionCode/versionName、签名配置、minSdk/targetSdk、abiFilters。

---

15. 附：与既有模块的关系