@feiyang666/dsh-mobile-remote 1.5.4 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 更新日志 / Changelog
 
+## v1.7.0 (2026-08-28)
+
+### 新增 / New
+- **中转服务器 WS 状态推送客户端**（`lib/ws-client.js` + `lib/external.js`）：外网隧道开启后，插件端改为通过 **WebSocket 长连接**（`/api/tunnel/ws?bindCode=…`）接收中转服务器的隧道状态实时推送，**替代原来每 5s 的 HTTP 轮询** `/api/tunnel/stats`，中转服务器请求压力降为 0（服务器资源集中用于 frp 隧道中转）。
+  - 指数退避自动重连（2s → 4s → … → 60s 封顶），断线自动恢复；
+  - `ws` 依赖缺失（如离线安装未带依赖）时自动降级：WS 客户端 no-op，心跳与状态查询回退 HTTP 低频兜底，**功能不中断**；
+  - 停止外网 / 插件卸载时主动断开，不再自动重连。
+- **心跳优先经 WS 长连接发送**（`lib/external.js` `sendHeartbeat`）：WS 已连上时心跳直接经长连接送达（零 HTTP 请求），未连上才回退 HTTP `/api/tunnel/heartbeat`。
+- **状态查询 60s 节流缓存**（`lib/index.js` `queryServerStatus`）：即使移动端前端每 5s 轮询本机 `/status`，也不会高频打中转服务器；前端 `/status` 优先读 WS 推送缓存，仅在从未收到推送（ws 缺失 / WS 未建立）时才回退 HTTP 低频查询。
+
+### 变更 / Changed
+- 新增运行时依赖 `ws`（`^8.18.0`）；`npm run check` / `prepublishOnly` 增加 `lib/ws-client.js` 语法检查。
+
+## v1.6.1 (2026-08-23)
+
+### 修复 / Fixed
+
+- **用量插件等宽表在移动端被压成逐字竖排（可靠兜底）**（`lib/index.js` MOBILE_CSS）：`dsh-usage-plugin` 的「消耗表 / 消耗明细 / 每日统计」等 9–11 列宽表依赖其运行时注入的全局样式（`.dsh-usage-table{min-width:720px}` + ≤540px 折叠中间列）来避免列被压到极限宽度；若该样式因 CSP / 加载时序未生效，手机窄屏下每列会被压到约 1 字符宽、内容逐字竖排、无法阅读。本插件（dsh-mobile-remote）的样式是**随 index.html 一起由服务端下发、必定生效**，故在 `<style id="dsh-mobile-remote-css">` 中新增兜底：`html[data-dsh-mobile] .dsh-usage-table { min-width: 720px !important; }`，并在 ≤540px 时对带 `collapse-mobile` 的宽表隐藏第 4 列至倒数第 2 列、只保留前 3 个主标识列与最后合计列。这样即使旧版用量插件未更新或其样式表注入失败，移动端宽表也始终可横向滑动阅读、关键数据一屏看全。价格表等窄表（无 `collapse-mobile`）不折叠，保留横向滚动。
+
+## v1.6.0 (2026-08-23)
+
+### 新增 / New
+- **SSE 实时推送端点**（`lib/index.js`）：新增 `GET /__dsh_remote/events` 事件流端点（受远程密码门禁保护），设备心跳上报 / 远程开关切换 / 外网隧道启动停止等状态变化时向订阅者推送 `data: {"type":"changed","at":<时间戳>}`。桌面端数据中心等客户端订阅该流即可即时感知远程设备与隧道状态变化，无需轮询。无订阅者时零开销，插件独立使用不受影响。
+
 ## v1.5.4 (2026-08-23)
 
 ### 新增 / New

package/RELEASE_NOTES.md

@@ -1,4 +1,4 @@
-# dsh-mobile-remote v1.5.4
+# dsh-mobile-remote v1.7.0
 
 **DeepSeek Harness 移动端远程控制插件** —— 在 Web UI 设置页内置「远程控制」：连接二维码、一键开关、在线设备数，让手机通过局域网访问并操控电脑上的 DeepSeek Harness。移动端提供上传图片入口、底部抽屉式模型选择、发送状态提示等移动优先体验。
 
@@ -10,52 +10,23 @@ dsh plugin --profile web add @feiyang666/dsh-mobile-remote
 
 安装完成后**重启 dsh web 服务**，打开 `http://127.0.0.1:3080` → **设置 → 远程控制** 即可使用。
 
-## 本版更新（v1.5.4）
+## 本版更新（v1.7.0）
 
-### 🐛 修复移动端无法选择图片（v1.5.0 起就存在的根因）
+### 🆕 中转服务器 WS 状态推送（长连接替代轮询）
 
-图片类型校验正则写为 `/^image\//i`，但该代码经 JS **模板字符串**注入 `<script>`，模板字符串中 `\/` 属于非转义序列、反斜杠会被丢弃，注入后变成 `/^image//i`，被解析成「正则 `/^image/` 除以 `i.test(...)`」，运行时报 `TypeError: i.test is not a function`——从 v1.5.0 起手机端选图后输入框一直没有缩略图。本版改用 `indexOf('image/')` 判断图片类型，彻底绕开正则转义问题。
+外网隧道开启后，插件端改为通过 **WebSocket 长连接**（`/api/tunnel/ws?bindCode=…`）接收中转服务器的隧道状态实时推送，**替代原来每 5s 的 HTTP 轮询** `/api/tunnel/stats`，中转服务器请求压力降为 0（服务器资源集中用于 frp 隧道中转）。
 
-同时配套修复：
-- 图片 intake 不再依赖 `new DataTransfer()`（iOS Safari 上 `files` 为空、`getAsFile()` 返回 null），改用普通 JS 对象模拟 `clipboardData` / `dataTransfer` 接口；
-- 模拟 `clipboardData` 补齐 DSH `onPaste` 会调用的 `getData()`，避免 React 事件处理器崩溃；
-- 隐藏文件选择器改为等 `document.body` 就绪后再挂载，避免部分 iOS WebView 拒绝 `.click()` 打开系统相册。
+- **指数退避自动重连**：断线后 2s → 4s → … → 60s 封顶自动恢复；
+- **心跳优先走 WS**：WS 已连上时心跳经长连接送达（零 HTTP 请求），未连上才回退 HTTP 兜底；
+- **状态查询 60s 节流**：即使移动端每 5s 轮询本机 `/status`，也不会高频打中转服务器；前端优先读 WS 推送缓存；
+- **ws 依赖缺失自动降级**：`ws` 未安装时 WS 客户端 no-op，心跳与状态查询回退 HTTP 低频兜底，**功能不中断**。
 
-### 🆕 移动端「上传中 / 发送中」状态指示
+> ⚠️ 本版新增运行时依赖 `ws`（`^8.18.0`）。通过 `dsh plugin --profile web add` 安装会自动带上；若使用离线 tgz 手动安装，请确保 `ws` 已安装（缺失时插件自动降级，不会崩溃）。
 
-发送图片消息时，DSH 会先 `serializeImages`（读取图片转 base64，移动端大图可能持续数秒）再 `prompt`，期间会话列表不会立刻出现新消息，用户容易误以为「没发出去」。本版监听 composer textarea 的 `data-phase`，进入 `submitting` / `adjudicating` 阶段时在 composer 上方显示带 spinner 的浮层提示：
+## 历史更新（v1.6.x）
 
-- 有附件图片时显示「正在上传图片并发送…」；
-- 纯文本时显示「正在发送…」；
-- 发送完成（phase 恢复）后自动隐藏。
-
-### 🐛 模型选择弹窗在移动端改为底部抽屉
-
-ModelSelect 菜单为绝对定位浮层（`right: 0`、宽 240px），窄屏下从右侧锚点向左展开，把 composer 左侧的 + / 上传图片等按钮盖住。本版将带 `aria-label` 的 `[role=menu]`（模型选择菜单）在移动端改为**底部抽屉（bottom sheet）**：贴底、左右留 8px、距底部 24px、宽度自适应屏幕、`max-height: 62vh` 内部滚动，不再遮挡左侧内容；权限选择菜单保持原有浮层 + 水平钳制。
-
-## 历史更新（v1.5.0）
-
-### 🆕 移动端上传图片（composer 加号旁的「上传图片」按钮）
-
-DSH 桌面端原生支持图片消息（粘贴 / 拖放，含格式 / 数量 / 大小预检查、缩略图 rail、随消息上传），但移动端没有「选择图片」的入口——工具行的 + 按钮只打开命令菜单。本版在**移动端 composer 工具行、+ 加号按钮旁**注入一个「上传图片」按钮：
-
-- 点击按钮，直接唤起手机**系统相册 / 文件选择器**（支持一次选多张）；
-- 选中后把图片喂给 DSH **原生 intake 链路**（`paste` / `drop` 事件），格式 / 数量 / 大小预检查、缩略图预览、随消息上传全部复用官方实现；
-- **不依赖 DSH 内部 API**，harness 升级后只要 paste / drop 链路仍在即可正常工作；
-- 按钮禁用态跟随输入框（session 移除 / 锁定 / 提交中自动置灰）；选完文件自动重置，可重复选同一张图；
-- 配套优化：缩略图 rail 删除按钮触控目标加大（18px → 24px），选图失败时自备极简提示气泡。
-
-> 仅移动端（`<1024px`）生效，桌面端界面不受任何影响。
-
-### 🐛 修复启用远程控制后写坏 profile 的 cordis.patch.yml（服务启动即崩溃）
-
-在设置页开启「远程控制」并重启服务后，dsh 启动即崩溃。**根因**：官方模板生成的 profile patch 文件内容是 `[]`（空数组占位），插件往文件末尾追加列表块时未先移除占位行，导致同一文件出现两个 YAML 文档且无 `---` 分隔符。**修复**：写入前过滤掉裸 `[]` 占位行（`setPatchEnabled` / `ensureTrustedHost`）。
-
-### 🐛 修复客户端插件加载失败（client-modules: loaded without registering）
-
-client 侧 bundle 中 `__ModuleLoader__.load` 的 `id` 写成了无 scope 的裸包名，改为完整包名 `@feiyang666/dsh-mobile-remote`，与官方插件的 client bundle 写法一致。
-
-> 已安装旧版本的用户：请先卸载本插件（桌面端「插件管理」或 `dsh plugin --profile web remove @feiyang666/dsh-mobile-remote`），再重新安装本修复版。
+- **v1.6.1**：用量插件等宽表移动端兜底（强制 720px + ≤540px 折叠中间列）
+- **v1.6.0**：新增 `GET /__dsh_remote/events` SSE 实时推送端点（设备心跳 / 远程开关 / 外网隧道状态变化即时推送）
 
 ## 已知事项
 

package/lib/external.js

@@ -6,7 +6,8 @@
 //   - 写 profile 的 connection trustedHosts，放行外网域名（通过 /api 信任围栏）
 //   - 心跳上报、状态查询、停止
 //
-// 零运行时依赖：仅 Node 内置模块。frpc 二进制由中转服务提供或用户本地放置。
+// 运行时依赖：Node 内置模块 + `ws`（WebSocket 长连接接收中转服务状态推送，
+// 替代高频轮询；ws 依赖缺失时自动回退 HTTP 低频查询）。frpc 二进制由中转服务提供或用户本地放置。
 //
 // 稳健性说明（针对"开启难/开了又关"问题）：
 //   - 强制给 frpc.toml 追加 loginFailExit=false：连不上 frps 时持续重试，
@@ -22,6 +23,7 @@ import {
   existsSync, readFileSync, writeFileSync, mkdirSync, openSync, closeSync, rmSync,
 } from 'node:fs'
 import { spawn } from 'node:child_process'
+import { createWsStatusClient } from './ws-client.js'
 
 /** 默认中转服务地址（自建 dsh-update-server，Nginx 反代 443→3200，对外无端口）。
  *  可用 DSH_REMOTE_SERVER 覆盖。 */
@@ -480,6 +482,19 @@ async function startExternalInner(state, body, patchFile, defaultLocalPort) {
       state.serverBase = base
       state.localPort = Number((body && body.localPort) || defaultLocalPort)
       savePersistedState(state)
+      // 建立 WS 长连接接收隧道状态推送（替代每 5s HTTP 轮询中转服务器）；
+      // ws 依赖缺失（离线安装）时 wsClient.connect() 自动 no-op，心跳走 HTTP 兜底
+      state.serverStatus = null
+      if (state.wsClient) {
+        try { state.wsClient.disconnect() } catch { /* ignore */ }
+      }
+      state.wsClient = createWsStatusClient({
+        serverBase: base,
+        bindCode: state.bindCode,
+        onStatus: (data) => { state.serverStatus = data },
+        logger: null,
+      })
+      state.wsClient.connect()
       // 隧道确认建立后启动持续心跳，让后端 last_seen 保持新鲜（管理端在线判定依赖它）
       startKeepAlive(state)
     }
@@ -568,6 +583,12 @@ async function startExternalInner(state, body, patchFile, defaultLocalPort) {
  */
 function stopExternal(state, opts = {}) {
   stopKeepAlive(state)
+  // 断开 WS 长连接（中转服务端据此判定离线）
+  if (state.wsClient) {
+    try { state.wsClient.disconnect() } catch { /* ignore */ }
+    state.wsClient = null
+  }
+  state.serverStatus = null
   // 停止前上报离线，让管理端/成员端立即反映（后端支持 status 字段才生效）
   if (!opts.keepState) {
     state.status = 'offline'
@@ -612,20 +633,23 @@ function frpcLogTail(bytes = 6000) {
 /** 持续心跳间隔（毫秒）：后端据此维持 last_seen，并做离线超时判定。 */
 const HEARTBEAT_INTERVAL = 60_000
 
-/** 上报一次在线/离线心跳（尽力而为，失败静默）。 */
+/** 上报一次在线/离线心跳（尽力而为，失败静默）。
+ *  优先经 WS 长连接发送（零 HTTP 请求）；WS 不可用/未连上时回退 HTTP。 */
 async function sendHeartbeat(state) {
   const base = state.serverBase || process.env.DSH_REMOTE_SERVER || DEFAULT_SERVER_BASE
   const bindCode = state.bindCode
   if (!bindCode) return
+  const status = state.status === 'online' ? 'online' : 'offline'
+  // WS 已连接 → 直接经长连接发送，减轻中转服务器 HTTP 压力
+  if (state.wsClient && state.wsClient.isOpen() && state.wsClient.sendHeartbeat(status)) {
+    return
+  }
+  // WS 不可用 / 未连上 → HTTP 心跳兜底（旧后端 / ws 依赖缺失场景）
   try {
     await fetch(`${base.replace(/\/$/, '')}/api/tunnel/heartbeat`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        bindCode,
-        // offline 表示隧道已停止，让管理端立即标记离线（后端支持时才生效）
-        status: state.status === 'online' ? 'online' : 'offline',
-      }),
+      body: JSON.stringify({ bindCode, status }),
     })
   } catch { /* ignore */ }
 }

package/lib/index.js

@@ -59,6 +59,19 @@ const HEARTBEAT_TTL = 90_000
 /** 心跳清理定时器间隔（毫秒）。 */
 const HEARTBEAT_SWEEP = 30_000
 
+// ---- SSE 实时推送 ----
+// 设备心跳 / 远程开关 / 外网隧道状态变化时通知订阅者（订阅端点 /__dsh_remote/events）。
+// 无订阅者时是 no-op，插件独立使用不受影响。
+const sseClients = new Set()
+
+function notifyChanged() {
+  if (sseClients.size === 0) return
+  const payload = 'data: {"type":"changed","at":' + Date.now() + '}\n\n'
+  for (const res of sseClients) {
+    try { res.write(payload) } catch (e) { sseClients.delete(res) }
+  }
+}
+
 /**
  * 插件入口。webServer 服务就绪后被调用。
  * @param {import('@deepseek-ai/cordis').Context} ctx
@@ -104,6 +117,8 @@ export function apply(ctx) {
       ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/external/stop', handler: authGate(handleExternalStop(ctx, external)) }),
       // frpc 运行日志读取（供设置页展示外网隧道详细状态）
       ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/external/log', handler: authGate(handleExternalLog()) }),
+      // —— SSE 实时事件流：设备心跳 / 远程开关 / 外网隧道状态变化时推送 {"type":"changed"} ——
+      ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/events', handler: authGate(handleEvents()) }),
       // —— 远程访问密码门禁相关（auth 系列不套 authGate，需放行）——
       ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/auth-status', handler: handleAuthStatus() }),
       ctx.webServer.register({ kind: 'exact', path: '/__dsh_remote/auth', handler: handleAuth() }),
@@ -415,6 +430,21 @@ function authGate(handler) {
   }
 }
 
+/** GET /__dsh_remote/events：SSE 实时事件流。设备心跳 / 远程开关 / 外网隧道状态变化时推送。 */
+function handleEvents() {
+  return (req, res) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    })
+    res.write(':ok\n\n')
+    sseClients.add(res)
+    req.on('close', () => { sseClients.delete(res) })
+  }
+}
+
 /** GET /__dsh_remote/auth-status：返回远程访问密码的启用状态与本次请求是否需鉴权。 */
 function handleAuthStatus() {
   return async (req, res) => {
@@ -572,11 +602,18 @@ self.addEventListener('fetch', function (event) {
 
 /**
  * 从中转服务器查询本成员隧道状态与统计；失败时返回 null（不影响整体 status）。
+ * 仅作 WS 推送不可用（ws 依赖缺失 / 旧后端）时的 HTTP 兜底。
  * 优先调用 /api/tunnel/stats（含 frps 实时流量/连接数等），接口不可用则回退到
- * /api/tunnel/status（旧版后端）。任一失败返回 null。
+ * /api/tunnel/status（旧版后端）。
+ * 注意：带 60s 节流缓存——即使前端每 5s 轮询本机 /status，也不会高频打中转服务器。
  */
+let serverStatusCache = { at: 0, value: null }
 async function queryServerStatus(base, bindCode) {
   if (!bindCode) return null
+  const now = Date.now()
+  if (serverStatusCache.value && now - serverStatusCache.at < 60000) {
+    return serverStatusCache.value
+  }
   const server = String(base || DEFAULT_SERVER_BASE).replace(/\/$/, '')
   const call = (path) => fetch(`${server}${path}`, {
     headers: { Accept: 'application/json' },
@@ -589,8 +626,9 @@ async function queryServerStatus(base, bindCode) {
   }).catch(() => null)
   const q = `?bindCode=${encodeURIComponent(bindCode)}`
   const stats = await call(`/api/tunnel/stats${q}`)
-  if (stats) return stats
-  return call(`/api/tunnel/status${q}`)
+  const data = stats || await call(`/api/tunnel/status${q}`)
+  serverStatusCache = { at: now, value: data }
+  return data
 }
 
 /** 当前 profile 的 cordis.patch.yml 绝对路径。 */
@@ -700,10 +738,11 @@ function handleStatus(ctx, devices, external, tracker, dshCache) {
       })
     }
     deviceList.sort((a, b) => b.lastSeen - a.lastSeen)
-    // 外网隧道在线时，向中转服务器查询成员真实状态（成员名 / frps 在线 / 最后心跳）
+    // 外网隧道在线时，优先读 WS 推送缓存（经长连接实时更新，零中转服务器请求）；
+    // 仅当从未收到推送（ws 依赖缺失 / WS 未建立）时才回退 HTTP 低频查询（60s 节流）。
     let server = null
     if (extRunning && persisted) {
-      server = await queryServerStatus(persisted.serverBase || undefined, persisted.bindCode)
+      server = external.serverStatus || await queryServerStatus(persisted.serverBase || undefined, persisted.bindCode)
     }
     json(res, 200, {
       host: ctx.webServer.host,
@@ -767,6 +806,7 @@ function handleToggle(ctx) {
     const enabled = body.enabled === true
     try {
       const result = setPatchEnabled(ctx, enabled)
+      notifyChanged() // 远程开关变化：通知 SSE 订阅者
       json(res, 200, {
         ok: true,
         enabled,
@@ -818,6 +858,7 @@ function handleHeartbeat(devices, tracker) {
       firstSeen: prev ? prev.firstSeen : now,
       lastSeen: now,
     })
+    notifyChanged() // 设备状态更新：通知 SSE 订阅者
     json(res, 200, { ok: true, deviceCount: devices.size })
   }
 }
@@ -864,9 +905,11 @@ function handleExternalStart(ctx, external) {
     try {
       const patchFile = patchFilePath(ctx)
       const result = await startExternal(external, body, patchFile, ctx.webServer.port || 3080)
+      notifyChanged() // 外网隧道启动：通知 SSE 订阅者
       json(res, 200, Object.assign({ ok: true }, result))
     } catch (error) {
       external.error = String(error?.message || error)
+      notifyChanged() // 启动失败也通知（前端可感知错误状态）
       json(res, 500, { ok: false, error: external.error })
     }
   }
@@ -876,6 +919,7 @@ function handleExternalStart(ctx, external) {
 function handleExternalStop(ctx, external) {
   return async (req, res) => {
     stopExternal(external)
+    notifyChanged() // 外网隧道停止：通知 SSE 订阅者
     json(res, 200, { ok: true, enabled: false })
   }
 }
@@ -1360,6 +1404,30 @@ html[data-dsh-mobile] [data-composer-card] [role='menu'][aria-label] {
   overflow: hidden !important;
   overscroll-behavior: contain !important;
 }
+
+/* ----- 移动端插件宽表兜底：防止被压成逐字竖排 -----
+ * dsh-usage-plugin 的「消耗表 / 消耗明细 / 每日统计」等 9–11 列宽表依赖其
+ * 自身在运行时注入的全局样式（.dsh-usage-table{min-width:720px} + ≤540px
+ * 折叠中间列）来避免列被压到极限宽度。若该样式因 CSP 或加载时序未生效，
+ * 手机窄屏下每列会被压到约 1 字符宽、内容逐字竖排、数据无法阅读。
+ * 本插件（dsh-mobile-remote）的样式是随 index.html 一起由服务端下发的，
+ * 必定生效，因此作为可靠兜底：
+ *   - 宽表强制 min-width:720px，配合其外层 overflow-x 容器横向滑动，始终可读；
+ *   - ≤540px 时对带 collapse-mobile 的宽表隐藏第 4 列至倒数第 2 列，只保留
+ *     前 3 个主标识列 + 最后合计列，手机上一屏即可看全关键数据；
+ *   - 价格表等窄表（无 collapse-mobile）不折叠，保留横向滚动。
+ */
+html[data-dsh-mobile] .dsh-usage-table {
+  min-width: 720px !important;
+}
+@media (max-width: 540px) {
+  html[data-dsh-mobile] .dsh-usage-table.collapse-mobile tr > *:not(:nth-child(-n+3)):not(:last-child) {
+    display: none !important;
+  }
+  html[data-dsh-mobile] .dsh-usage-table.collapse-mobile {
+    min-width: 320px !important;
+  }
+}
 `
 
 /* ------------------------------------------------------------------ */

package/lib/ws-client.js

@@ -0,0 +1,152 @@
+// dsh-mobile-remote — 中转服务器 WS 状态推送客户端（host 侧）。
+//
+// 目标：用 WebSocket 长连接接收中转服务器的隧道状态推送，替代插件端
+// 每 5s 轮询 /api/tunnel/stats，把中转服务器的请求压力降为 0。
+//
+// 说明：
+//  - 本插件运行在 Electron 内置 Node（当前 20.x，无原生全局 WebSocket），
+//    因此需要 `ws` 第三方库。若依赖缺失（如离线 tgz 安装未装依赖），
+//    wsAvailable() 返回 false，调用方自动回退 HTTP 低频查询，功能不中断。
+//  - 连接管理：指数退避自动重连（2s→4s→…→60s）；心跳由 external.js 的
+//    keepAliveTimer 统一驱动（每 60s），WS 已连上时走 WS、否则走 HTTP。
+//  - 收到 tunnel:status 后更新本地缓存并回调 onStatus，前端 /status 直接读缓存。
+
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+/** 尝试加载 ws 库（Node 20 无原生 WebSocket，需要它）。 */
+let WsCtor = null
+try {
+  WsCtor = require('ws')
+} catch {
+  WsCtor = null
+}
+
+/** 当前环境是否可用 WebSocket（ws 依赖是否加载成功）。 */
+export function wsAvailable() {
+  return !!WsCtor
+}
+
+/**
+ * 创建成员端 WS 状态推送客户端。
+ * @param {object} opts
+ * @param {string} opts.serverBase 中转服务基地址（https://… 或 http://…）
+ * @param {string} opts.bindCode    绑定码
+ * @param {(data: object) => void} [opts.onStatus] 收到 tunnel:status 时的回调
+ * @param {(msg: string, ...args: unknown[]) => void} [opts.logger] 日志（默认静默）
+ */
+export function createWsStatusClient({ serverBase, bindCode, onStatus, logger }) {
+  let ws = null
+  let manualClose = false
+  let retryTimer = null
+  let retryDelay = 2000
+  let lastStatus = null
+  const log = logger || (() => {})
+
+  function wsUrl() {
+    // http:// → ws://，https:// → wss://
+    const base = String(serverBase || '').replace(/^http/, 'ws').replace(/\/+$/, '')
+    return `${base}/api/tunnel/ws?bindCode=${encodeURIComponent(String(bindCode || ''))}`
+  }
+
+  function isOpen() {
+    return !!(ws && ws.readyState === ws.OPEN)
+  }
+
+  function scheduleReconnect() {
+    if (manualClose || retryTimer) return
+    retryTimer = setTimeout(() => {
+      retryTimer = null
+      connect()
+    }, retryDelay)
+    if (retryTimer.unref) retryTimer.unref()
+    retryDelay = Math.min(retryDelay * 2, 60000)
+  }
+
+  function connect() {
+    if (!WsCtor) return
+    if (manualClose) return
+    if (ws && (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING)) return
+    let client
+    try {
+      client = new WsCtor(wsUrl())
+    } catch (e) {
+      log('[ws-client] 连接失败:', String((e && e.message) || e))
+      scheduleReconnect()
+      return
+    }
+    ws = client
+
+    client.on('open', () => {
+      retryDelay = 2000
+      log('[ws-client] 已连接（bindCode=****）')
+    })
+
+    client.on('message', (buf) => {
+      try {
+        const msg = JSON.parse(buf.toString())
+        if (msg && msg.type === 'tunnel:status' && msg.data) {
+          msg.data._at = Date.now() // 缓存新鲜度标记
+          lastStatus = msg.data
+          try { onStatus && onStatus(msg.data) } catch (e) { /* ignore */ }
+        }
+      } catch (e) { /* ignore */ }
+    })
+
+    client.on('close', (code, reason) => {
+      log('[ws-client] 连接关闭 code=' + code, String(reason || ''))
+      ws = null
+      if (!manualClose) scheduleReconnect()
+    })
+
+    client.on('error', (err) => {
+      log('[ws-client] 错误:', String((err && err.message) || err))
+      try { client.terminate() } catch (e) { /* ignore */ }
+    })
+  }
+
+  /** 主动断开（停止外网 / 插件卸载时调用），之后不再自动重连。 */
+  function disconnect() {
+    manualClose = true
+    if (retryTimer) { clearTimeout(retryTimer); retryTimer = null }
+    if (ws) {
+      try { ws.close() } catch (e) { /* ignore */ }
+      try { ws.terminate() } catch (e) { /* ignore */ }
+      ws = null
+    }
+  }
+
+  /** 重置并重连（绑定码 / 中转地址变化后使用）。 */
+  function reconnect() {
+    manualClose = false
+    if (retryTimer) { clearTimeout(retryTimer); retryTimer = null }
+    retryDelay = 2000
+    if (ws) {
+      try { ws.terminate() } catch (e) { /* ignore */ }
+      ws = null
+    }
+    connect()
+  }
+
+  /**
+   * 经 WS 发送心跳（成功返回 true；未连接返回 false，调用方回退 HTTP）。
+   * @param {'online'|'offline'} [status]
+   */
+  function sendHeartbeat(status) {
+    if (!isOpen()) return false
+    try {
+      ws.send(JSON.stringify({ type: 'heartbeat', status: status || 'online' }))
+      return true
+    } catch (e) {
+      return false
+    }
+  }
+
+  /** 最近一次收到的隧道状态（未收到过为 null）。 */
+  function getLastStatus() {
+    return lastStatus
+  }
+
+  return { connect, disconnect, reconnect, isOpen, sendHeartbeat, getLastStatus }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feiyang666/dsh-mobile-remote",
-  "version": "1.5.4",
+  "version": "1.7.0",
   "description": "DeepSeek Harness mobile remote-control plugin: LAN/external remote control (QR / on-off toggle / remote-access password gate), rich telemetry (expandable device details, system CPU/memory/load, DSH app state: version/sessions/workspaces/plugins/models), real external-tunnel status detection (frpc token / reconnect diagnostics), mobile-first UI polish (composer image upload entry via system picker, settings single-column layout) and faster remote loading.",
   "keywords": [
     "deepseek",
@@ -40,6 +40,9 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -62,8 +65,8 @@
   ],
   "scripts": {
     "pack:list": "npm pack --dry-run",
-    "check": "node --check lib/index.js && node --check lib/client.js && node --check lib/external.js && node --check lib/password.js && node --check lib/qrcode.js",
-    "prepublishOnly": "node --check lib/index.js && node --check lib/client.js && node --check lib/external.js && node --check lib/password.js && node --check lib/qrcode.js",
+    "check": "node --check lib/index.js && node --check lib/client.js && node --check lib/external.js && node --check lib/ws-client.js && node --check lib/password.js && node --check lib/qrcode.js",
+    "prepublishOnly": "node --check lib/index.js && node --check lib/client.js && node --check lib/external.js && node --check lib/ws-client.js && node --check lib/password.js && node --check lib/qrcode.js",
     "pack": "npm pack"
   },
   "peerDependencies": {