feat(clients): 设备桥自动链接改用服务端发现 + 路径挂载（无 DNS 依赖）

配套 webui 反代改造：网关现在可由 HomeAgent 反代出去，客户端不能再靠
「门户地址同 host 拼 /api/v1/device/ws」猜地址——基域名与子域标签都是
**服务端配置**，客户端无从得知。

## 服务端：/api/v1/device/gateway 发现端点

客户端问「网关在哪」是唯一不会漂移的做法：子域标签可改（插件声明）、
基域名可改（webui.base_domain）、实例可换形态，客户端都不用跟着改。

⚠️ **不返回设备令牌**：本端点用门户凭证鉴权，而设备令牌能执行设备命令；
把令牌塞进来等于「门户只读凭证 → 设备执行权」的越权。令牌仍由客户端
自配。已有判据钉住「不得泄漏凭证字段」。

## ★ 实测发现：*.localhost 只有浏览器能解析

这是本轮最重要的发现，直接决定了设计：

| 环境 | devices.localhost 解析 |
|---|---|
| 浏览器 | ✓（RFC 6761 内置） |
| curl | ✓（内置特例） |
| getent / Go / Node | ✗（系统 nsswitch 是 files,dns，无 nss-myhostname） |

设备客户端（waiter / GUI 主进程 / 嵌入式固件）用的正是系统解析器。
实测 waiter 报「lookup devices.localhost on 192.168.2.1:53」。

因此**两处**设计变更：
1. 发现端点同时返回两种形态，并标 preferred：
   - url（子域）—— 浏览器用
   - url_portal（门户同源，同一 host、同一端口，走路径挂载）—— 非浏览器用，
     无任何 DNS 依赖
2. SDK 的 ProxyDecl 新增 **Path**（路径挂载前缀）：让同一服务同时挂到
   门户自身 host 的路径下。remotedevice 声明 Path="/api/v1/device"，
   设备客户端因此能沿用**它已硬编码的路径**，不需要知道反代存在。

路径挂载语义：请求路径**原样保留**（不剥前缀），上游按真实路径注册即可。
边界卡在路径分隔符上（/api/v1/device 不匹配 /api/v1/devicefoo）。

## 客户端

- **waiter**：新增 discoverGateway()，仅在用户配了门户地址时尝试，失败回退
  自配地址（老版本 HomeAgent 无该端点）。抽出 normalizeGateway() 纯函数，
  显式钉住「已带子域/完整端点的地址不得被改写」。
- **GUI**：renderer 新增 loadDiscoveredGateway()，renderDeviceChannel 优先用
  发现值、回退旧口径。顺带修掉此前插入函数时 anchor 不匹配导致调用点
  找不到定义的问题。
- **鸿蒙**：discoverGateway() + resolveGatewayUrl()，优先 url_portal。
- 三者都**优先 url_portal**（system resolver 的现实约束）。

## 遗留路由鉴权修正

`/api/v1/device/` 的旧路径反代原被 requireAPI 包裹 —— 但其调用方是设备
（带设备令牌而非门户凭证），套上门户鉴权会把它们全挡在 401（**真实实测**：
waiter 经此路径升级握手 401）。去掉这层包装，鉴权交给上游 remotedevice
自己的 requireToken，安全性不降级。

## 判据

webui +6 条、waiter +7 条。

★ 其中一条是**真实回归**：/api/v1/device/gateway 曾被 Path="/api/v1/device"
的路径挂载接走（那服务 auth=none），于是发现请求被转给上游、回 401，
客户端再也发现不到网关。修法是发现端点先于路径挂载判定，并补判据
（走完整生产链，同时确认同前缀的真实设备路径仍归反代）。

## 真实验收（隔离实例，命名 netns + 独立 data + 18080）

真 waiter 客户端 + 真 remotedevice 网关：
  device gateway discovered: ws://127.0.0.1:18080/api/v1/device/ws
  device bridge active: waiter-mainserver authorized=true
  hello_ack / bind_ack 均经反代往返成功

说明：`bind_ack device=<nil>` 与在线列表为空的现象，**直连 9890 绕开反代
完全一致复现**，属 remotedevice 与 waiter 之间既有的握手细节，与本次
反代改造无关（反代侧职责已证：连接建立 + 双向帧往返都通）。

cmd/ohos/HomeAgent/entry/src/main/ets/common/DeviceBridgeSession.ets

@@ -1,4 +1,5 @@
 import { common } from '@kit.AbilityKit';
+import { http } from '@kit.NetworkKit';
 import { deviceBridge } from './DeviceBridge';
 import { installCmdRouter, setBridgeAppContext } from './BridgeRouter';
 import { LOCAL_DEVICE_CAPS, shutdownSpeakerUse } from './BridgeCaps';
@@ -24,7 +25,14 @@ function ensureBridgeStateTracking(): void {
   });
 }
 
-/** 把当前后端 HTTP 地址转换为同源设备桥 WebSocket 地址。 */
+/**
+ * 把门户 HTTP 地址转换为同源设备桥 WebSocket 地址（**回退路径**）。
+ *
+ * 网关改造为子域反代后位于 devices.<基域名>，而基域名与子域标签都是**服务端
+ * 配置**，客户端拼不出来。正常路径是先调 discoverGateway() 问服务端；
+ * 本函数只在「服务端没有发现端点」（老版本 HomeAgent）时兜底，
+ * 保留旧部署的可用性。
+ */
 export function deviceGatewayUrl(base: string): string {
   let trimmed: string = base.trim();
   while (trimmed.length > 0 && trimmed.charAt(trimmed.length - 1) === '/') {
@@ -50,6 +58,72 @@ export function deviceGatewayUrl(base: string): string {
  * 应用进入前台后建立全局设备桥。它不再依赖用户先打开“设备”Tab，
  * 因而 screensue、clipboardsee 等前台能力从主页面加载后即可接收。
  */
+/**
+ * 向门户询问设备网关的**权威地址**。
+ *
+ * 为什么必须问而不是自己拼：网关现在挂在 devices.<基域名> 子域上，基域名
+ * （webui.base_domain，默认 localhost）与子域标签（插件声明里可改）都在
+ * 服务端，客户端无从得知。服务端作答是唯一不会漂移的做法。
+ *
+ * 失败/老版本（404）不报错，返回空串让调用方回退到 deviceGatewayUrl()——
+ * 发现是增强而非必需。
+ */
+async function discoverGateway(portalUrl: string, apiKey: string): Promise<string> {
+  let base: string = portalUrl.trim();
+  if (base.length === 0) {
+    return '';
+  }
+  // 用户配置里可能填的是完整网关地址：截到门户根再拼发现路径
+  const cut: number = base.indexOf('/api/v1/');
+  if (cut >= 0) {
+    base = base.substring(0, cut);
+  }
+  while (base.length > 0 && base.charAt(base.length - 1) === '/') {
+    base = base.substring(0, base.length - 1);
+  }
+  try {
+    const r = await http.createHttp().request(base + '/api/v1/device/gateway', {
+      method: http.RequestMethod.GET,
+      header: { 'X-API-Key': apiKey } as Record<string, string>,
+      connectTimeout: 5000,
+      readTimeout: 5000,
+    });
+    if (r.responseCode !== 200) {
+      return '';
+    }
+    const body: string = typeof r.result === 'string' ? r.result : '';
+    const parsed: Record<string, Object> = JSON.parse(body) as Record<string, Object>;
+    // 服务端明确报告不可用（没有声明设备网关反代）时不返回地址，
+    // 让调用方回退，而不是拿着一个连不上的 URL 反复重连。
+    if (parsed['available'] !== true) {
+      return '';
+    }
+    // 优先**门户同源形态**（url_portal：同一 host、同一端口）。
+    //
+    // 原因：子域形态 devices.<基域名> 依赖 DNS 解析，而 *.localhost 只有
+    // 浏览器内置该特例（RFC 6761）—— 应用内 HTTP/WS 客户端走系统解析器，
+    // 通常解析不到。门户同源形态无任何 DNS 依赖，永远可解析。
+    const portal: string = parsed['url_portal'] as string;
+    if (portal !== undefined && portal !== null && portal.length > 0) {
+      return portal;
+    }
+    const url: string = parsed['url'] as string;
+    return url === undefined || url === null ? '' : url;
+  } catch (e) {
+    // 网络失败 / 老版本无此端点：静默回退
+    return '';
+  }
+}
+
+/** 解析设备桥最终使用的网关地址：优先服务端发现，回退同源推导。 */
+async function resolveGatewayUrl(portalUrl: string, apiKey: string): Promise<string> {
+  const discovered: string = await discoverGateway(portalUrl, apiKey);
+  if (discovered.length > 0) {
+    return discovered;
+  }
+  return deviceGatewayUrl(portalUrl);
+}
+
 export async function startForegroundBridge(context: common.UIAbilityContext): Promise<void> {
   foregroundActive = true;
   setBridgeAppContext(context);
@@ -67,8 +141,9 @@ export async function startForegroundBridge(context: common.UIAbilityContext): P
   const generation: number = bridgeGeneration;
   const deviceId: string = connStore.ensureDeviceId();
   try {
+    const gatewayUrl: string = await resolveGatewayUrl(cur.url, cur.apiKey);
     await deviceBridge.connect(
-      deviceGatewayUrl(cur.url), cur.apiKey, deviceId,
+      gatewayUrl, cur.apiKey, deviceId,
       LOCAL_DEVICE_CAPS, 'ohos-phone', connStore.getDeviceAuth(), connStore.getDeviceName());
     if (!foregroundActive || generation !== bridgeGeneration) {
       deviceBridge.disconnect();