@feiyang666/dsh-mobile-remote 1.9.1 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 更新日志 / Changelog
 
+## v2.0.0 (2026-11-07)
+
+> 适配 **dsh 0.2.2-rc.1**。这一版修掉两个真实故障，并把自研移动端适配全部删除。
+
+### 修复 / Fixed
+
+- **局域网能访问但面板显示「未开启」、没有二维码**：dsh 用 `--host <网卡IP>` 启动时只监听那块
+  网卡（`127.0.0.1` 上没有任何监听），旧版旁挂听众去绑同一个 `<网卡IP>:<端口>` 必然
+  `EADDRINUSE`，于是 `running=false`。新增 `bindInfo()` 区分两种形态：
+  `direct`（宿主自己绑网卡）直接视为「局域网已可达」，只补其余网卡并跳过宿主已占用的地址。
+- **外网域名 502 Bad Gateway**：frpc 配置里的 `localIP = "127.0.0.1"` 指向没人监听的端口。
+  现在 `localIP` 跟随宿主真实监听地址；并新增**外网入口 30s HTTP 可达性探测**，
+  502 / 连不上会直接在设置页标红并显示 frpc 实际转发地址（进程活着不再等于「在线」）。
+
+### 移除 / Removed（官方已自带移动端适配）
+
+- 移动端 CSS 全部删除（composer 换行、选择器限宽、iOS 16px 防缩放、Tooltip 抑制、
+  设置页单栏、菜单水平钳制、侧栏抽屉样式）。
+- 「上传图片」按钮与图片 intake（模拟 paste/drop）删除 —— 官方 `+ → 文件` 与粘贴/拖放已覆盖。
+- 自研 Toast、composer 发送状态浮层、侧栏悬浮按钮 / 覆盖式抽屉、设置弹窗结构打标。
+- 保留设备心跳脚本（设置页「已连接设备」）、`crypto.randomUUID` 内网兜底（在门禁脚本内）、
+  远程访问密码门禁。
+
+### 变更 / Changed
+
+- `lib/lanproxy.js`：`start(hosts, port, { upstreamHost, skipHosts })`；`status()` 增加 `upstream`。
+- `lib/index.js`：`/status` 增加 `direct`、`lan.upstream`、`external.localHost`、`external.probe`。
+- `lib/client.js`：直连形态开关置灰 + 「局域网直连 · 由 dsh 提供」说明卡；外网卡片展示探测结果。
+- `lib/external.js`：`startExternal(..., localHost)`、`autoRestoreExternal(..., localHost)`；
+  导出 `finalizeFrpcConfig` 供测试。
+
+### 测试 / Tests
+
+- 新增 `tests/bind-aware.test.mjs`（4 项）：上游可定制、`skipHosts` 不重复绑、
+  全部地址被占用时不误报失败、frpc `localIP` 跟随宿主。
+- `tests/patch.test.mjs` 43 项断言仍全部通过。
+
 ## v1.9.1 (2026-10-24)
 
 ### 修复 / Fixed

package/README.md

@@ -188,8 +188,9 @@ So for users, **installing is one command** — no YAML editing, no manual file
 - **Toggle**: `POST /__dsh_remote/toggle` → writes/removes a `webserver` override block in the profile's `cordis.patch.yml` → dsh's `watchUserPatches` (Cordis HMR) hot-reloads the webserver entry to re-listen.
 - **Device count**: mobile-injected JS heartbeats every 30s; the host keeps an active-device map (90s TTL). Each heartbeat now reports full device metadata (screen / viewport / DPR / network / current page / language / platform), shown in the expandable device rows of the settings panel.
 - **QR code**: `GET /__dsh_remote/qr?url=...` returns SVG.
-- **Mobile polish**: `tapIndex` injects mobile CSS/JS — composer toolbar wraps on narrow screens, selects get width-capped, iOS inputs get 16px to prevent focus zoom, and an **"Upload image" button is injected next to the + in the composer toolbar** (system file picker → DSH's native paste/drop image-intake pipeline); **DSH's native rail + hamburger drawer interactions are untouched**;
-- **Mobile settings page** (v1.4.2+): the native settings dialog becomes a full-screen single column on phones — the nav rail turns into a horizontally scrollable tab bar and the content column fills the remaining space; persistent native tooltip bubbles (e.g. the "stop / start / close sidebar" hints that stick on touch) are suppressed. The dialog is detected structurally, **not via harness-internal hashed class names**, so the plugin keeps working after DeepSeek Harness updates without modification. **v1.4.3** fixes the single-column settings layout — the panel was still a row-flex, collapsing the content column to zero width (blank content) and blocking vertical scroll; it now forces `flex-direction: column` plus `min-height: 0` so the options area actually scrolls on phones. It also adds a **`crypto.randomUUID` fallback for insecure contexts (LAN `http://`)**: current DSH clients call `crypto.randomUUID()` on the wire, which is only defined on HTTPS or localhost, so LAN direct access failed with `crypto.randomUUID is not a function` / `settings are unavailable in this browser`; the injected head script now provides an RFC 4122 v4 shim backed by `getRandomValues`.
+- **No mobile UI patches any more** (v2.0.0): `tapIndex` only injects a ~40-line device-heartbeat script (`CLIENT_JS`). dsh 0.2.2+ already ships the mobile layout (drawer sidebar below 768px, auto-collapse at 1024px, no focus stealing on mobile UA, iOS keyboard fix, PWA), so the old mobile CSS, sidebar drawer, "Upload image" button, toast and sending indicator were removed — duplicated adaptation only fights the official implementation.
+- **`crypto.randomUUID` fallback for insecure contexts** (kept in `GATE_JS`): DSH clients call `crypto.randomUUID()` on the wire; it only exists on HTTPS or localhost, so LAN `http://` access used to fail with `settings are unavailable in this browser`. The injected head script provides an RFC 4122 v4 shim backed by `getRandomValues`.
+- **Tunnel reachability probe** (v2.0.0): frpc being alive only means it logged into frps. Every 30s the host now issues an HTTP probe against the public URL, so a 502 (wrong local forward address/port) is surfaced in the panel together with the local address frpc actually forwards to.
 
 ---
 

package/README.zh.md

@@ -6,7 +6,7 @@
 
 [GitHub](https://github.com/feiyang-dev/dsh-mobile-remote) · [npm](https://www.npmjs.com/package/@feiyang666/dsh-mobile-remote) · MIT License
 
-**由开发者制作的 DeepSeek Harness 插件** —— 在 Web UI 设置页内置「远程控制」：连接二维码、一键开关、在线设备数，让手机通过局域网访问并操控电脑上的 DeepSeek Harness，同时提供移动端界面优化。
+**由开发者制作的 DeepSeek Harness 插件** —— 在 Web UI 设置页内置「远程控制」：连接二维码、一键开关、在线设备数，让手机通过局域网/外网访问并操控电脑上的 DeepSeek Harness（移动端界面由官方 dsh 自带，插件不再注入 UI 补丁）。
 
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-339933)
@@ -20,16 +20,15 @@
 
 `dsh-mobile-remote` 是 DeepSeek Harness 生态的**移动端远程控制插件**（DSH plugin，Host + Client 双面一体包）。装好后在 WebUI **设置 → 远程控制** 出现一个管理面板：
 
-- **移动端上传图片**（v1.5.0）：composer 工具行 **+ 加号旁新增「上传图片」按钮**，手机直接选图（系统相册 / 文件选择器）即可让 DeepSeek 识图模型识别——格式 / 数量 / 大小预检查、缩略图预览、随消息上传全部复用 DSH 原生链路，桌面端不受影响；
-- **移动端侧栏默认收起**（v1.9.0）：窄屏下把侧栏轨道压到 0，内容区吃满整屏；左上角悬浮按钮点开为**覆盖式抽屉**（不挤压中栏），点遮罩 / Esc / 选中会话自动收起；
+- **不再自带移动端 UI 补丁**（v2.0.0）：官方 dsh 0.2.2 起已内置移动端适配（<768px 侧栏浮层抽屉 + 遮罩、1024px 自动塌缩、移动 UA 不抢焦点、iOS 软键盘修正、PWA），插件只保留一个设备心跳脚本；旧的移动端 CSS、侧栏抽屉、「上传图片」按钮、Toast 与发送状态浮层**全部移除**，界面完全交回官方实现；
 - **连接二维码**：自动生成 `http://<局域网IP>:<端口>` 的二维码，手机相机 / 浏览器扫码即连；
 - **裸地址直达，自动登录**（v1.8.0）：直接访问裸地址 `http://192.168.x.x:3080`（不带任何 token）即可自动进入——服务端自动完成新版 dsh 的浏览器会话认证（`≥0.1.2-rc.1`），无需复制带 `?token=` 的长链接；老版 dsh 自动回退，行为不变；
-- **开启 / 关闭开关**（v1.9.0 重做）：在局域网网卡上**旁挂一个转发听众**（`<局域网IP>:<端口>` → `127.0.0.1:<端口>`），dsh 自身的监听地址与端口**完全不动**——本机窗口、桌面端、会话都不会被打断，开关**即时生效、无需重启、不写配置**；
+- **开启 / 关闭开关**（v2.0.0 适配两种绑定形态）：dsh 只听回环时，在局域网网卡上**旁挂一个转发听众**（`<局域网IP>:<端口>` → `127.0.0.1:<端口>`）；dsh 自己就用 `--host <网卡IP>` 启动时，直接以那块网卡为上游、只补其余网卡（同地址不再重复绑，避免 `EADDRINUSE` 导致「明明能访问却显示未开启」）。dsh 的监听地址与端口**完全不动**——本机窗口、桌面端、会话都不会被打断，开关**即时生效、无需重启、不写配置**；
 - **当前连接的设备数量**：移动端心跳上报，实时统计在线设备数；
 - **远程访问密码门禁**（v1.2.0+）：管理员本机设置密码，外网隧道访问进入页面需先输密码，本机/局域网不受影响；
 - **远程访问提速**（v1.2.0+）：frpc 连接池调大，缓解外网访问首屏转圈慢；
 - **更丰富的数据展示**（v1.4.0）：设备列表可点击展开完整上报信息（系统 / 浏览器 / 屏幕 / 视口 / DPR / 设备内存 / CPU 核数 / 电池 / 网络 / 当前页面 / 首次连接 / 心跳次数）；「运行时信息」卡（运行时长 / 开机时长 / Node 版本 / PID / CPU 型号与核数 / 系统负载 / 内存使用率 / RSS / 堆内存）；**「DSH 状态」卡**（dsh 版本 / 会话总数 / 工作区列表 / 已安装插件 / 模型提供方，后台缓存）；「网络接口」卡（网卡名 / IP / 掩码 / MAC）；外网隧道详情（域名 / 端口 / frpc 版本 / PID / 运行时长 / 脱敏绑定码 / 日志查看）；
-- **外网隧道真实状态**（v1.4.1）：不再"假在线"——面板探测 frpc 日志确认隧道真正建立，断线重连降级「连接中」，token 鉴权失败显示红色「出错」+ 精确原因（如 `token in login doesn't match`）+ 一键重试；中转端 `FRP_TOKEN` 占位符时显示黄色警告条；隧道持续心跳保活，让中转端在线状态真实可靠；
+- **外网隧道真实状态**（v1.4.1+ / v2.0.0 增强）：面板探测 frpc 日志确认隧道真正建立，断线重连降级「连接中」，token 鉴权失败显示红色「出错」+ 精确原因（如 `token in login doesn't match`）+ 一键重试；**v2.0.0 起每 30 秒再对外网入口做一次 HTTP 探测**——frpc 进程活着只代表连上了 frps，本机转发地址/端口不对时中转侧对外只会回 502，现在这种「假在线」会直接在面板上标红，并显示 frpc 实际使用的本地转发地址；
 - 局域网地址列表、手机访问地址、配置位置一目了然。
 
 **核心卖点：纯命令行用户无需安装桌面端。** 官方 CLI 出于安全拒绝 `--host 0.0.0.0`；而 dsh **0.2.1-rc.3 起连 patch 层也不再接受通配地址**（`host: '0.0.0.0'` 会在配置校验阶段直接让进程退出），改绑具体网卡又会让本机回环监听消失（桌面端窗口白屏）。所以 v1.9.0 改用**旁挂 LAN 听众**：dsh 保持只听回环，插件在局域网网卡上再监听一份并转发过去——手机与电脑仍共享同一个后端进程与同一份 `~/.dsh` 数据，**会话列表、历史记录、工作区、设置全部天然双向同步，无需任何数据复制**。
@@ -185,9 +184,8 @@ dsh --profile web --patch remote-control.patch.yml
 - **开关**：`POST /__dsh_remote/toggle` → 在局域网网卡上开启 / 关闭旁挂听众。请求被转发到 `127.0.0.1:<端口>`，并把 `Host` / `Origin` 改写成回环 authority（dsh 的信任围栏对回环一律放行），因此**不需要改 dsh 任何配置、也不需要重启**。
 - **设备数**：移动端注入 JS 每 30s 心跳上报，host 维护活跃设备表（90s 过期）。每次心跳会上报完整设备元数据（屏幕 / 视口 / DPR / 网络 / 当前页面 / 语言 / 平台），设置面板的设备行可展开查看。
 - **二维码**：`GET /__dsh_remote/qr?url=...` 返回 SVG。
-- **移动端适配**：`tapIndex` 注入移动端 CSS/JS，composer 输入栏窄屏换行、选择器限宽、iOS 输入框 16px 防缩放、**加号旁注入「上传图片」按钮**（文件选择器选图 → 复用 DSH 原生 paste/drop intake 链路）；
-- **移动端侧栏**（v1.9.0）：窄屏下侧栏轨道压到 `0px`，内容区吃满整屏；左上角悬浮按钮唤出**覆盖式抽屉**（半透明遮罩，点遮罩 / Esc / 选中会话自动收起）。仍复用原生 toggle 按钮驱动官方 store，只把「挤压中栏」改写成「浮层」，因此原生 aria / 快捷键 / 状态一致；框架节点用 `data-dsh-mobile-frame` 标记，不依赖 harness 哈希类名；
-- **移动端设置页适配**（v1.4.2+）：原生设置弹窗在手机上自动变为全屏单栏——导航栏变顶部横向滚动标签、内容区占满剩余空间；同时抑制触屏上常驻的原生 Tooltip 气泡（如「停止 / 开始 / 关闭菜单栏」提示文字）。通过结构标记识别设置弹窗，**不依赖 harness 内部哈希类名**，harness 升级后无需修改插件即可直接适配。**v1.4.3** 修复该单栏布局——面板原本仍是横向 `flex`，内容列被压成 0 宽度（内容空白）且无法上下滚动；现强制 `flex-direction: column` + `min-height: 0`，设置选项区在手机上可正常滚动。并新增**内网（非安全上下文）`crypto.randomUUID` 兜底**：当前 DSH 客户端在连接时直接调用 `crypto.randomUUID()`，该 Web Crypto API 仅在 HTTPS / localhost 存在，内网 http 直连会报 `crypto.randomUUID is not a function` / `settings are unavailable in this browser`；插件注入的头部脚本用 `getRandomValues` 补一个 RFC 4122 v4 实现，内网访问 / 扫码连接恢复正常。
+- **前端只注入心跳脚本**（v2.0.0 起）：`tapIndex` 只插一个约 40 行的设备心跳脚本（`lib/index.js` 的 `CLIENT_JS`），**不再注入任何移动端 CSS / 交互补丁**——官方 dsh 0.2.2 已自带窄屏抽屉、软键盘修正等适配，重复适配只会与官方改动打架；
+- **内网（非安全上下文）`crypto.randomUUID` 兜底**（保留，见 `GATE_JS`）：当前 DSH 客户端连接时直接调用 `crypto.randomUUID()`，该 Web Crypto API 仅在 HTTPS / localhost 存在，内网 http 直连会报 `crypto.randomUUID is not a function` / `settings are unavailable in this browser`；门禁脚本用 `getRandomValues` 补一个 RFC 4122 v4 实现，内网访问 / 扫码连接正常。
 
 ---
 

package/RELEASE_NOTES.md

@@ -1,46 +1,36 @@
-# dsh-mobile-remote v1.9.1
+# dsh-mobile-remote v2.0.0
 
-> v1.9.1 仅修复 1.9.0 的 npm 包内误带了一个本地备份文件（`lib/patch.js.bak-0000`）的问题，
-> 功能与 v1.9.0 完全一致，无代码变更。
+**DeepSeek Harness 远程访问插件** —— 在 Web UI 设置页内置「远程控制」：连接二维码、一键开关、在线设备数，让手机通过局域网 / 外网访问并操控电脑上的 DeepSeek Harness。移动端界面从 v2.0.0 起**完全交给官方 dsh**（0.2.2 已自带）。
 
-**DeepSeek Harness 移动端远程控制插件** —— 在 Web UI 设置页内置「远程控制」：连接二维码、一键开关、在线设备数，让手机通过局域网访问并操控电脑上的 DeepSeek Harness。
+## 本版更新（v2.0.0）
 
-## 本版更新（v1.9.0）—— 让远程控制在 dsh 0.2.1+ 上重新可用
+一句话：**适配「dsh 自己就绑在网卡上」的启动方式，并把外网 502 从"假在线"里揪出来；同时删掉所有自研移动端 UI 补丁。**
 
-一句话：**不再改 dsh 的监听绑定，改为旁挂一个局域网听众。** 桌面端窗口、端口、会话全都不受影响。
+### 修掉的两个真实故障
 
-### 为什么之前的版本用不了了
+| 症状 | 根因 | 修复 |
+| --- | --- | --- |
+| 局域网明明能访问，插件却显示**未开启**、**不显示二维码** | dsh 用 `--host 192.168.x.x` 启动时只监听那块网卡，`127.0.0.1` 上没有任何监听。旧版旁挂听众去绑**同一个** `<网卡IP>:<端口>` → `EADDRINUSE` → `running=false` | 新增 `bindInfo()`：`direct` 形态直接认定「局域网已可达」，只补其余网卡并跳过宿主已占用的地址；二维码/地址列表把宿主绑定地址排第一 |
+| 外网域名打开就是 **502 Bad Gateway**，面板却显示「在线」 | frpc 配置里的 `localIP = "127.0.0.1"` 转发到一个没人监听的端口，frps 与 nginx 侧只能回 502 | frpc 的 `localIP` 跟随宿主真实监听地址（非回环时改成网卡 IP）；并新增**外网入口 30s HTTP 可达性探测**，502 直接在面板标红 |
 
-| 症状 | 根因 |
-| --- | --- |
-| 开启开关后，**电脑上的窗口直接打不开/白屏** | 旧版把 `webserver.host` 改成 `0.0.0.0`。dsh 0.2.1-rc.3 起只接受具体网卡 IP，`0.0.0.0` 会让进程启动即退出；即使是具体 IP，改绑后 `127.0.0.1` 监听消失，桌面端固定连回环 → 白屏 |
-| **官方桌面端**里开关点了完全没反应 | 旧版按 `DSH_PROFILE` 环境变量定位 profile，而官方桌面端**不设该变量**（只把 profile 目录作为 argv 传参）→ patch 写进了 `profiles/web`，实际运行的是 `profiles/desktop` |
-| 写完 patch 后 **dsh 起不来**，报 `unknown tag !<tag:yaml.org,2002:js>` | `!!js` 在该 YAML schema 里只能作用于**标量**；`trustedHosts: !!js [...]` 会被当成「流式序列 + 标量标签」 |
-| 端口莫名变了、二维码/链接失效 | 官方桌面端用 `--port 0` 由系统分配端口，旧 patch 里重述 `port` 会让重载后的端口漂移 |
+### 移动端适配全部移除
 
-### 新版怎么做的
+官方 dsh 0.2.2 起自带移动端适配（`<768px` 侧栏浮层抽屉 + 遮罩、`1024px` 自动塌缩、移动 UA 不抢焦点、iOS 软键盘光标修正、PWA 清单），继续注入自己的 CSS 只会和官方改动互相打架：
 
-- **旁挂 LAN 听众（`lib/lanproxy.js`）**：在 `<局域网IP>:<当前端口>` 再监听一份，反向代理到
-  `127.0.0.1:<当前端口>`。HTTP 与 WebSocket 都通，`X-Forwarded-For` 透传真实手机 IP，
-  长连接不会被 keep-alive 超时误杀。**开关即时生效，无需重启 dsh、不写任何配置文件。**
-- **Host / Origin 改写成回环**：dsh 的 Host/Origin 信任围栏对回环一律放行，
-  因此局域网访问**不再需要** `trustedHosts`，也不会再出现「页面能打开、`/api` 全 403」。
-- **patch 只写 `connection.trustedHosts`**（外网隧道经 frp 直连真实监听时才需要），
-  用 `!!js "[...ctx.webStartup.trustedHosts, '域名']"` 合并启动参数，绝不覆盖 `webserver`。
-- **profile 路径校正**：优先 `profileContext.patchPath` —— CLI、官方桌面端、第三方壳全部适用。
-- **旧配置自动迁移**：清理历史遗留的 `webserver` 覆盖与 `ctx.webRuntime.trustedHosts` 块，
-  迁出的域名并入受管 trustedHosts；若旧绑定正在生效，会在 HMR watcher 就绪后再改写，把监听拉回回环。
+- 删除全部移动端 CSS（composer 换行 / 选择器限宽 / 16px 防缩放 / Tooltip 抑制 / 设置页单栏 / 菜单钳制 / 抽屉样式）；
+- 删除「上传图片」按钮与模拟 paste/drop 的图片 intake 逻辑（官方 `+ → 文件` 与粘贴/拖放链路已有）；
+- 删除自研 Toast、发送状态浮层、侧栏悬浮按钮与抽屉、设置弹窗结构打标；
+- 保留：设备心跳脚本（设置页「已连接设备」需要）、`crypto.randomUUID` 内网兜底（在门禁脚本里）、远程访问密码门禁。
 
-### 移动端体验
+### 其它
 
-- **侧栏默认收起**：窄屏下侧栏轨道压到 `0px`，内容区吃满整屏（此前固定的 56px 图标 rail 在
-  390px 手机上仍占 14% 宽）。
-- **悬浮按钮唤出抽屉**：左上角悬浮汉堡按钮 → 覆盖式抽屉（不再挤压中栏）+ 半透明遮罩；
-  点遮罩 / Esc / 选中会话自动收起。开合仍驱动官方 store（复用原生 toggle、aria、快捷键）。
-- 端口变化时局域网听众 15s 内自适应重绑；`remoteEnabled` 持久化，重启自动恢复。
+- `lib/lanproxy.js`：`start(hosts, port, { upstreamHost, skipHosts })`，转发上游可定制、已占用地址自动跳过；`status()` 增加 `upstream`。
+- `lib/index.js`：`/status` 新增 `direct`（宿主直连形态）与 `lan.upstream`；`toggle` 在直连形态返回 `direct: true` 并说明需要改启动参数才能关闭；`external` 新增 `localHost` / `probe`。
+- `lib/client.js`：直连形态下开关置灰并显示「局域网直连 · 由 dsh 提供」说明卡；外网卡片展示入口探测结果。
+- 版本号提升到 **2.0.0**（移除移动端 UI 属于行为变更）。
 
 ### 验证
 
-- `tests/patch.test.mjs`：43 项断言全通过（含「绝不写 webserver」「`!!js` 必须加引号」「旧配置迁移」）。
-- 实测环境：dsh 0.2.1-rc.3 + Windows；验证了「本机端口不变 + 局域网同端口可访问 +
-  扫码自动登录 + `/api` 不再 403 + WebSocket 升级透传 + 开关即时生效（无需重启）」。
+- `node --test tests/patch.test.mjs`：43 项断言通过。
+- 新增 `tests/bind-aware.test.mjs`：4 项断言通过（上游可定制、`skipHosts` 不重复绑、全部被占用时不误报失败、frpc `localIP` 跟随宿主）。
+- 实测环境：Windows + dsh 0.2.2（`--host 192.168.3.119 --port 3080`）。修复前：`127.0.0.1:3080` = `ECONNREFUSED`，`/status` 返回 `remoteEnabled:false`，公网域名 nginx 502；修复后 `direct` 形态下 `remoteEnabled:true`、二维码正常，frpc `localIP` 改为宿主网卡地址。

package/cordis.patch.yml

@@ -8,7 +8,10 @@
 #
 # 插件是 host + client 双面插件：
 #   - host 侧（lib/index.js，inject [webServer]）：
-#       * 通过 ctx.webServer.tapIndex 注入移动端响应式 CSS / JS；
+#       * 局域网：宿主只绑回环时旁挂 LAN 听众；宿主用 --host <网卡IP> 启动时直接复用它；
+#       * 外网：经中转服务器 + frpc 隧道，并对公网入口做 30s 可达性探测（暴露 502）；
+#       * 通过 ctx.webServer.tapIndex 仅注入一个设备心跳脚本（不含任何移动端 UI 补丁，
+#         官方 dsh 0.2.2 起自带移动端适配）；
 #       * 通过 ctx.webServer.register 提供 /__dsh_remote/* API
 #         （status / toggle / heartbeat / qr），支持设置页远程控制开关、二维码、设备数。
 #   - client 侧（lib/client.js，package.json 的 dsh.client 声明）：

package/lib/client.js

@@ -332,21 +332,26 @@ window.__ModuleLoader__.load({
 
       // 局域网状态徽标
       var on = !!(status && status.remoteEnabled);
+      // dsh 自己就用 `--host <网卡IP>` 绑在网卡上（官方桌面端/第三方壳的启动方式）：
+      // 这时局域网直连由 dsh 提供，插件的旁挂听众既不需要也无法绑同一地址。
+      var direct = !!(status && status.direct && status.direct.enabled);
       var badge = el('span', { style: Object.assign({}, st.badge, on ? st.badgeOn : st.badgeOff) },
-        on ? '已开启' : '未开启');
+        on ? (direct ? '已开启（直连）' : '已开启') : '未开启');
 
-      // 局域网开关
+      // 局域网开关（直连形态下不可切换：那份监听属于 dsh 进程本身）
       var sw = el('button', {
         type: 'button',
         role: 'switch',
         'aria-checked': String(on),
-        'aria-label': on ? '关闭远程控制' : '开启远程控制',
+        'aria-label': direct ? '局域网直连由 dsh 启动参数提供' : (on ? '关闭远程控制' : '开启远程控制'),
         onClick: toggle,
-        disabled: busy || !status,
-        style: Object.assign({}, st.switch, on ? st.switchOn : null),
+        disabled: busy || !status || direct,
+        title: direct ? 'dsh 以 --host 启动了网卡监听，插件无法关闭；请修改启动参数' : null,
+        style: Object.assign({}, st.switch, on ? st.switchOn : null, direct ? { opacity: .65, cursor: 'default' } : null),
       }, el('span', { style: Object.assign({}, st.knob, on ? st.knobOn : null) }));
 
       // 局域网二维码（裸地址：插件已在服务端接管 / 自动完成认证，无需带 token）
+      // lanAddresses 由 host 排序：直连形态下宿主自己的绑定地址排第一。
       var bareLanUrl = (status && status.lanAddresses && status.lanAddresses.length && status.port)
         ? ('http://' + status.lanAddresses[0] + ':' + status.port)
         : (status && status.url || null);
@@ -519,6 +524,20 @@ window.__ModuleLoader__.load({
             : (extError ? '外网隧道异常，请查看上方错误信息' : '开启外网访问后，这里显示外网二维码'));
       }
 
+      // 外网入口真实可达性探测：frpc「在线」只代表连上了 frps，
+      // 本地服务不可达时中转侧对外一律 502 —— 必须把这一层单独暴露出来。
+      var extProbe = status && status.external ? status.external.probe : null;
+      var extProbeEl = null;
+      if (extStarted && extProbe) {
+        var probeBad = extProbe.ok !== true;
+        extProbeEl = el('p', { style: probeBad ? Object.assign({}, st.hint, { color: '#c0272b' }) : st.hint },
+          probeBad
+            ? '外网入口探测失败：' + (extProbe.error || ('HTTP ' + extProbe.status)) +
+              '（frpc 本地转发 ' + ((status.external && status.external.localHost) || '127.0.0.1') +
+              ':' + (status.port || '') + '）'
+            : '外网入口可达（HTTP ' + extProbe.status + '；每 30 秒自动复检）');
+      }
+
       // 说明卡片（未开启时展示新版工作原理）
       var cliHint = null;
       if (status && !status.remoteEnabled) {
@@ -534,6 +553,20 @@ window.__ModuleLoader__.load({
         );
       }
 
+      // 直连说明（dsh 用 --host <网卡IP> 启动时）
+      var directHint = null;
+      if (status && direct) {
+        directHint = el('div', { style: st.card },
+          el('div', { style: st.row },
+            el('p', { style: st.title }, '局域网直连'),
+            el('span', { style: Object.assign({}, st.badge, st.badgeOn) }, '由 dsh 提供')),
+          el('p', { style: st.sub },
+            'dsh 启动时带了 --host ' + ((status.direct && status.direct.host) || status.bindHost || '') +
+            '，本身就监听在这块网卡上，手机可以直接连接，不需要插件再旁挂听众。'),
+          el('p', { style: st.hint },
+            '因此这里的开关不可用：要彻底关闭局域网访问，需去掉 dsh 启动参数里的 --host（或改成 127.0.0.1）后重启。'));
+      }
+
       // ---- 远程访问密码管理 ----
       var authOn = !!(status && status.auth && status.auth.enabled);
       var authRequiredHere = !!(status && status.auth && status.auth.requiredHere);
@@ -1010,6 +1043,8 @@ window.__ModuleLoader__.load({
 
           extQr,
 
+          extProbeEl,
+
           extErrText
             ? el('div', { style: Object.assign({}, st.card, { borderColor: 'rgba(200,40,40,.35)' }) },
                 el('p', { style: Object.assign({}, st.hint, { color: '#c0272b' }) }, '外网访问失败：' + extErrText),
@@ -1021,6 +1056,8 @@ window.__ModuleLoader__.load({
                   el('button', { type: 'button', onClick: refresh, style: st.btn }, '刷新状态')))
             : null),
 
+        directHint,
+
         cliHint,
 
         error

package/lib/external.js

@@ -124,9 +124,10 @@ const POOL_COUNT_RE = /^\s*(transport\.)?poolCount\s*=.*(\r?\n|$)/gm
  *      连接复用 tcpMux 自动管理；服务端可能仍在下发该字段，本地一律剥离，
  *      否则 frpc 解析配置失败、启动即退出）。
  * @param {string} cfg - 后端返回的原始 frpc 配置
+ * @param {string} [localHost] - frpc 应当转发到的本地地址（宿主真实监听地址）
  * @returns {string} 修正后的配置
  */
-function finalizeFrpcConfig(cfg) {
+function finalizeFrpcConfig(cfg, localHost) {
   let text = String(cfg || '')
   // 3) 先剥离 client 端已不支持的 poolCount 字段（放最前，保证后续注入干净）
   text = text.replace(POOL_COUNT_RE, '')
@@ -140,7 +141,19 @@ function finalizeFrpcConfig(cfg) {
     }
     text = text.replace(/^(\s*serverAddr\s*=\s*)[^\n]+/m, `$1"${override.trim()}"`)
   }
-  // 2) loginFailExit 必须放顶层（第一个 [[proxies]] 之前），否则 frpc 解析报错
+  // 2.5) localIP 覆写：宿主如果只绑了某块网卡（官方桌面端/第三方壳的 `--host 192.168.x.x`），
+  //      127.0.0.1 上没有任何监听，frpc 转发过去就是 connection refused →
+  //      中转服务器/nginx 对外只能是 502 Bad Gateway。这里把代理的 localIP 改成宿主真实地址。
+  const target = String(localHost || '127.0.0.1').trim() || '127.0.0.1'
+  if (target !== '127.0.0.1') {
+    if (/^\s*localIP\s*=/m.test(text)) {
+      text = text.replace(/^(\s*localIP\s*=\s*)[^\n]*/gm, `$1"${target}"`)
+    } else {
+      // 没有 localIP 行时补在每条 localPort 之前（与 frp 配置顺序无关，读者更直观）
+      text = text.replace(/^(\s*localPort\s*=\s*)/gm, `localIP = "${target}"\n$1`)
+    }
+  }
+  // 3) loginFailExit 必须放顶层（第一个 [[proxies]] 之前），否则 frpc 解析报错
   if (!/loginFailExit\s*=/.test(text)) {
     const injectLine = '# 由 dsh-mobile-remote 注入：连不上 frps 时持续重试不退出\nloginFailExit = false\n'
     const proxiesIdx = text.indexOf('[[proxies]]')
@@ -351,7 +364,7 @@ async function ensureFrpcBinary(base) {
  * 启动外网隧道。做了稳健性处理，避免"反复点/开了又关"。
  * @returns {Promise<{ok:boolean, url?:string, status?:string, error?:string, message?:string, log?:string}>}
  */
-async function startExternal(state, body, patchFile, defaultLocalPort) {
+async function startExternal(state, body, patchFile, defaultLocalPort, localHost) {
   // 已运行则直接返回，避免重复点重复启动；
   // 但状态为 error（如鉴权失败）时允许重试：kill 旧进程并重新绑定。
   if (state.proc && state.proc.exitCode === null && state.status !== 'error') {
@@ -363,8 +376,9 @@ async function startExternal(state, body, patchFile, defaultLocalPort) {
 
   state.status = 'connecting'
   state.error = null
+  state.localHost = String(localHost || '127.0.0.1')
   try {
-    return await startExternalInner(state, body, patchFile, defaultLocalPort)
+    return await startExternalInner(state, body, patchFile, defaultLocalPort, state.localHost)
   } catch (error) {
     // 启动失败必须复位状态，否则前端会一直卡在"连接中"且无法关闭
     state.status = 'error'
@@ -373,7 +387,7 @@ async function startExternal(state, body, patchFile, defaultLocalPort) {
   }
 }
 
-async function startExternalInner(state, body, patchFile, defaultLocalPort) {
+async function startExternalInner(state, body, patchFile, defaultLocalPort, localHost) {
   // 端口优先级：调用方显式指定 > 当前真实监听端口。
   // 不再让过期的持久化 localPort 覆盖当前端口（否则 frpc 会转发到无人监听的端口）。
   const localPort = Number((body && body.localPort) || defaultLocalPort || 0)
@@ -401,7 +415,7 @@ async function startExternalInner(state, body, patchFile, defaultLocalPort) {
 
   // 2) 写 frpc.toml（含 loginFailExit=false 与回环地址覆写）
   const cfgPath = frpcConfigPath()
-  const frpcConfig = finalizeFrpcConfig(data.frpcConfig)
+  const frpcConfig = finalizeFrpcConfig(data.frpcConfig, localHost)
   // 防线：确认代理确实指向当前监听端口。错配时 frpc 会连不上本地服务，
   // 表现为外网域名 502 Bad Gateway（日志：connect to local service ... refused）。
   if (localPort) {
@@ -489,6 +503,9 @@ async function startExternalInner(state, body, patchFile, defaultLocalPort) {
       state.wsClient.connect()
       // 隧道确认建立后启动持续心跳，让后端 last_seen 保持新鲜（管理端在线判定依赖它）
       startKeepAlive(state)
+      // 同时开始探测外网入口的真实可达性：frpc 进程活着并不代表 nginx/中转侧能拿到
+      // 200 —— 本地服务没起来（端口/绑定地址不对）时对外就是 502，必须自己暴露出来。
+      startUrlProbe(state)
     }
 
     const probe = () => {
@@ -575,6 +592,7 @@ async function startExternalInner(state, body, patchFile, defaultLocalPort) {
  */
 function stopExternal(state, opts = {}) {
   stopKeepAlive(state)
+  stopUrlProbe(state)
   // 断开 WS 长连接（中转服务端据此判定离线）
   if (state.wsClient) {
     try { state.wsClient.disconnect() } catch { /* ignore */ }
@@ -601,7 +619,7 @@ function stopExternal(state, opts = {}) {
  * 重新绑定并拉起 frpc，免去每次手动输入验证码与中转服务地址。
  * 失败时把状态置为 error 并保留持久化，供用户手动处理或下次重启重试。
  */
-async function autoRestoreExternal(state, patchFile, defaultLocalPort) {
+async function autoRestoreExternal(state, patchFile, defaultLocalPort, localHost) {
   const saved = loadPersistedState()
   if (!saved) return
   try {
@@ -620,7 +638,7 @@ async function autoRestoreExternal(state, patchFile, defaultLocalPort) {
     if (stale && live && stale !== live) {
       state.lastLog = `检测到端口变化（持久化 ${stale} → 当前 ${live}），外网隧道已改用当前端口`
     }
-    await startExternal(state, body, patchFile, live || stale)
+    await startExternal(state, body, patchFile, live || stale, localHost)
   } catch (e) {
     state.status = 'error'
     state.error = `自动恢复外网访问失败：${String((e && e.message) || e)}`
@@ -709,6 +727,71 @@ function probeTunnelHealth(state) {
   return verdict
 }
 
+/* ------------------------------------------------------------------ */
+/* 外网入口可达性探测                                                    */
+/* ------------------------------------------------------------------ */
+
+/** 探测结果缓存：同一 URL 30 秒内不重复请求（status 每 5s 轮询一次）。 */
+let urlProbeCache = { url: '', at: 0, value: null }
+
+/**
+ * 用 HTTP GET 探测外网入口的真实状态。
+ * frpc 进程活着只代表「已经连上 frps」，不代表中转服务器能把请求送到本机：
+ * 本机端口没人监听 / 绑定地址不对时，nginx 对外一律回 502 —— 这里把它探测出来。
+ * @param {string} url - 外网访问地址（https://xxx）
+ * @returns {Promise<{ok: boolean, status: number, at: number, error?: string}|null>}
+ */
+async function probeExternalUrl(url) {
+  if (!url) return null
+  const now = Date.now()
+  if (urlProbeCache.url === url && now - urlProbeCache.at < 30_000) return urlProbeCache.value
+  let value
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      redirect: 'follow',
+      headers: { 'user-agent': 'dsh-mobile-remote/healthcheck' },
+      signal: AbortSignal.timeout(8000),
+    })
+    // 只用状态码判断可达性，正文直接丢弃（避免把整个前端页面读进内存）
+    try { await res.arrayBuffer() } catch { /* ignore */ }
+    value = {
+      ok: res.status >= 200 && res.status < 400,
+      status: res.status,
+      at: Date.now(),
+      error: res.status === 502
+        ? '中转服务器返回 502：frps 已连上，但本机端口没有响应（转发地址/端口不对，或 dsh 未监听该地址）'
+        : null,
+    }
+  } catch (error) {
+    value = { ok: false, status: 0, at: Date.now(), error: String((error && error.message) || error) }
+  }
+  urlProbeCache = { url, at: now, value }
+  return value
+}
+
+/** 启动外网入口可达性轮询（30s 一次，随隧道停止而停止）。 */
+function startUrlProbe(state) {
+  if (state.probeTimer) return
+  const tick = async () => {
+    if (!state.url) return
+    const value = await probeExternalUrl(state.url)
+    if (value) state.probe = value
+  }
+  void tick()
+  state.probeTimer = setInterval(() => { void tick() }, 30_000)
+  if (state.probeTimer.unref) state.probeTimer.unref()
+}
+
+/** 停止外网入口探测并清空缓存结果。 */
+function stopUrlProbe(state) {
+  if (state.probeTimer) {
+    clearInterval(state.probeTimer)
+    state.probeTimer = null
+  }
+  state.probe = null
+}
+
 /** 当前外网状态摘要（供 /status 使用）。 */
 function externalView(state) {
   const running = !!state.proc && state.proc.exitCode === null
@@ -737,6 +820,10 @@ function externalView(state) {
     pid: running && state.proc ? state.proc.pid : null,
     startedAt: state.startedAt || null,
     lastLog: state.lastLog || null,
+    // frpc 实际转发的本地地址（非回环时是宿主的网卡 IP）
+    localHost: state.localHost || null,
+    // 外网入口真实可达性：{ ok, status, at, error }
+    probe: state.probe || null,
     error,
   }
 }
@@ -746,6 +833,8 @@ export {
   externalDir,
   frpcBinaryPath,
   frpcConfigPath,
+  // 供单元测试直接断言配置改写（localIP / loginFailExit / poolCount）
+  finalizeFrpcConfig,
   startExternal,
   stopExternal,
   externalView,