@feiyang666/dsh-mobile-remote 1.1.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # 更新日志 / Changelog
 
+## v1.4.1 (2026-08-20)
+
+### 新增 / Added
+- **外网隧道真实状态判定**（`lib/external.js` + `lib/client.js`）：
+  - 开启外网时不再"进程活着 = 在线"，改为探测 frpc 日志确认隧道真正建立（`start proxy success`）才判 `online`；
+  - 新增 `probeTunnelHealth()`：`/status` 轮询时复查日志，发现断线（`connect to server error`）降级为「连接中」、token 不匹配（`token in login doesn't match`）降级为「出错」，重连成功后自动恢复在线；
+  - 前端新增红色「出错」徽标 + 错误卡，直接展示 frpc 真实报错与解决指引（服务器 `FRP_TOKEN` 与 `frps.toml` 的 `auth.token` 不一致等），并提供「查看 frpc 日志」按钮；
+  - `error` 状态支持一键重试（kill 旧进程重新绑定）。
+- **隧道持续心跳保活**（`lib/external.js`）：隧道在线期间每 60s 上报一次心跳，让中转端 `last_seen` 保持新鲜；停止隧道时主动上报 `offline`，配合后端在线判定实时反映真实状态。
+- **FRP_TOKEN 占位符检测**（前后端联动）：中转端 `/status`、`/stats` 返回 `frpTokenWarning`；插件面板显示黄色警告条，提示服务器 `.env` 的 `FRP_TOKEN` 仍是占位符导致隧道必然 502。
+- **DSH 状态卡默认折叠**（`lib/client.js`）：折叠态只显示摘要行（会话 / 工作区 / 插件 / 模型数），点击标题展开详情，节省面板空间。
+
+### 修复 / Fixed
+- **设置页空白崩溃**：修复 `status` 首次渲染为 `null` 时，`status.external...` 无守卫导致的 `Cannot read properties of null` 崩溃（面板内容区被错误边界吞成空白）；同时加固 `extErrText` 的完整守卫。
+- 外网状态不再被 `/status` 覆盖为假在线（`externalView` 直接透传真实状态）。
+
+### 变更 / Changed
+- `lib/client.js`：外网隧道卡新增 frpc 进程 PID / 已运行时长 / 脱敏绑定码展示。
+- 依赖后端 `dsh-update-server` 同步升级（成员端在线判定 / `/stats` / `heartbeat` 离线支持），旧后端自动回退兼容。
+
+## v1.4.0 (2026-08-20)
+
+### 新增 / Added
+- **运行时信息卡扩充**（host `lib/index.js`）：新增 CPU 型号 / 频率、系统负载（1m / 5m / 15m）、系统开机时长、内存使用率（%）。
+- **DSH 应用层状态卡**（host + client）：
+  - **版本号**：多位置探测 dsh 版本（profile 本地 / 桌面版 `dsh-local` / 全局安装）；
+  - **会话总数**：`ctx.sessionPersistence.list()`（带 2s 超时保护）；
+  - **工作区列表**：路径 / 标题 / 会话数（`ctx.workspaceRegistry.list()`）；
+  - **已安装插件列表**：插件名 / 启用状态 / fiber 阶段（`ctx.pluginInventory.list()`）；
+  - **模型提供方**：提供方 id / 名称（`ctx.llm.listProviders()`）。
+  - 以上数据由**后台每 60s 缓存刷新**，`/status` 直接读缓存，不拖慢 5s 轮询；任一服务不可用时自动降级隐藏。
+- **设备详情补强**（`MOBILE_JS` + host + client）：新增**设备内存（GB）/ CPU 核数 / 电池电量（含是否充电）**。
+- **外网隧道详情补强**（host + client）：新增 **frpc 进程 PID / 已运行时长 / 脱敏绑定码**（前 4 位 + `****`）。
+
+### 变更 / Changed
+- host 侧通过 `ctx.get()` 可选获取 `sessionPersistence` / `workspaceRegistry` / `pluginInventory` / `llm`，**不新增必选 inject 依赖**，保证精简启动方式下插件仍可正常运行。
+- `lib/external.js`：frpc 启动时记录 `startedAt`，停止时清除。
+
+## v1.3.0 (2026-08-20)
+
+### 新增 / Added
+- **更丰富的数据展示**（host `lib/index.js` + client `lib/client.js`）：
+  - **设备详情可展开**：已连接设备列表改为可点击展开，展示系统 / 浏览器、屏幕 / 视口 / DPR、触屏标记、网络连接（effectiveType / 下行带宽 / RTT）、在线状态、语言 / 平台、当前页面（标题 + 路径）、首次连接 / 最后活跃时间、心跳次数；
+  - **心跳元数据补全**：移动端心跳上报由原来的 `id + ua` 扩充为完整设备信息（`platform` / `lang` / `online` / `touch` / `dpr` / `screen` / `viewport` / `connection` / `path` / `title` / `mobile`）；
+  - **统计区扩充**：由 2 格变为 4 格 —— 当前连接设备 / 累计设备 / 累计心跳 / 局域网地址；
+  - **运行时信息卡**：运行时长、Node.js 版本、进程 PID、主机名、系统（平台 / 版本 / 架构）、CPU 核数、可用内存 / 总内存、RSS、堆内存、当前 Profile、DSH 数据目录；
+  - **网络接口卡**：所有 IPv4 网卡的网卡名 / IP / CIDR / 掩码 / MAC / 是否回环；
+  - **外网隧道详情**：域名、隧道端口、frpc 版本、中转服务器状态 / 最后心跳 / 服务器时间，以及「查看 frpc 日志」按钮（新 host API `GET /__dsh_remote/external/log`）。
+
+### 修复 / Fixed
+- **累计心跳数恒为 0**：`tracker.beats()` 之前只是读取、从不自增，导致 `totalHeartbeats` 永远为 0；改为 `recordBeat()` 每次心跳 +1。
+- 累计去重设备数 / 心跳数改为设备粒度统计（每台设备 `beatCount`）。
+
+### 变更 / Changed
+- `lib/external.js`：启动时探测并记录 frpc 版本（`state.frpcVersion`），供设置页展示；导出 `frpcLogTail()`。
+- `lib/client.js`：设置面板新增多个数据展示区块，布局保持主题 token 自适应深色 / 浅色。
+
+## v1.2.0 (2026-08-20)
+
+### 新增 / Added
+- **远程访问密码门禁**（host half `lib/index.js` + `lib/password.js` + client half `lib/client.js`）：
+  - 设置页「远程控制 → 远程访问密码」卡片：管理员本机设置 / 修改 / 清除密码；
+  - 远程（外网隧道 / HTTPS 反代）访问进入 DSH 页面时，弹出全屏密码验证页，输入正确密码方可使用；本机 / 局域网直连不受影响；
+  - 密码仅以 `scrypt` 哈希 + 随机盐存于本地 `~/.dsh/plugins/dsh-mobile-remote/config.json`，绝不落盘明文；`timingSafeEqual` 校验 + 登录失败次数限制防爆破；
+  - **完全本地、不依赖任何中转后端**（兼容自建 frp / 中转服务 / 其它中转方案）；
+  - 新增 host API：`/__dsh_remote/auth-status`、`auth`、`logout`、`set-password`；`/__dsh_remote/*` 对远程未认证请求返回 401。
+
+### 性能优化 / Performance
+- **远程访问加载提速**：`lib/external.js` 为生成的 `frpc.toml` 注入 `poolCount`（默认 20，可用 `DSH_FRPC_POOL_COUNT` 覆盖），缓解 DSH 首屏大量并发请求触发 frpc “work connection pool is full” 导致的转圈/排队；
+- 配套：服务端模板 `deploy/frps.toml` 调大 `transport.maxPoolCount` 到 64（部署后生效）。
+
 ## v1.1.0 (2026-08-19)
 
 ### 新增 / Added

package/README.md

@@ -23,12 +23,50 @@
 - **Connection QR code**: auto-generates a QR for `http://<lan-ip>:<port>` — scan it with your phone's camera / browser to connect.
 - **On / Off toggle**: switches the webserver listen address (`0.0.0.0` ↔ `127.0.0.1`) with one click. Applied via dsh's official HMR hot-reload — **no service restart needed**.
 - **Connected device count**: mobile heartbeats report online devices in real time.
+- **Remote access password gate** (v1.2.0+): set a password locally; external-tunnel visitors must enter it before the page loads — local/LAN access stays password-free.
+- **Faster remote loading** (v1.2.0+): larger frpc connection pool to stop the slow initial spinner over tunnels.
+- **Rich telemetry** (v1.4.0): click any connected device to expand its full reported details (OS / browser / screen / viewport / DPR / device memory / CPU cores / battery / network / current page / first-seen / heartbeat count); a system-runtime card (uptime / boot time / Node version / PID / CPU model & cores / load average / memory usage / RSS / heap); a **DSH app-state card** (dsh version, session count, workspace list, installed plugins, model providers — cached in the background); per-interface network details (name / IP / mask / MAC); and external-tunnel details (domain / port / frpc version / PID / uptime / masked bind code / live log viewer).
+- **Real external-tunnel status** (v1.4.1): no more fake "online" — the panel probes frpc's log to confirm the tunnel is really up, downgrades to "connecting" during reconnects, and shows a red **error card with the exact frpc reason** (e.g. `token in login doesn't match`) plus a one-click retry; FRP_TOKEN placeholder warnings from the relay show as a yellow banner; keep-alive heartbeats keep the relay's online state truthful.
 - LAN address list, phone access URLs, and config location at a glance.
 
 **Key selling point: pure CLI users don't need the desktop app.** The official CLI deliberately rejects `--host 0.0.0.0` for safety, but this plugin writes `webserver.host: 0.0.0.0` through the profile's `cordis.patch.yml` (or a `--patch <overlay>`) — exactly how the desktop app's "Mobile Remote Control" switch works. The phone and the computer share the same dsh backend process and the same `~/.dsh` data, so **sessions, history, workspace and settings are naturally two-way synced — no data copying involved**.
 
 ---
 
+## Remote Access Password (customizable / self-hostable)
+
+To make **remote (external-tunnel) access** safer, the plugin ships a **remote access password gate**:
+
+- In **Settings → Remote Control → "Remote Access Password"**, an admin sets / changes / clears a password **locally**;
+- Once set, any browser reaching this DSH **through the external tunnel (`*.dsh.xxx.top`, HTTPS reverse-proxied)** is blocked by a full-screen password page and **must enter the correct password** to use it; local (`127.0.0.1`) and LAN-direct access are unaffected, so the admin can always log in locally to manage / repair;
+- The password is stored **entirely locally** (`~/.dsh/plugins/dsh-mobile-remote/config.json`) as an **scrypt hash + random salt — never plaintext**, verified with `timingSafeEqual` (timing-attack safe) and rate-limited to prevent brute force.
+
+> **Key design: fully local, decoupled from any relay backend.** Whether you use the bundled `dsh-update-server` relay or self-host any other frp / tunneling solution (including a different relay service), the password gate works directly — it applies to any "remote HTTPS access" and does not depend on your relay.
+
+---
+
+## Backend (dsh-update-server) API
+
+The plugin's external-tunnel status uses the relay server's **member-side** endpoints (no admin login):
+
+- `GET /api/tunnel/status` — basic member status (name / online / port / last-seen).
+- `GET /api/tunnel/stats` — **rich member tunnel stats** (added in this release, requires the relay server to be updated): same basic fields plus live **frps** proxy details — today's inbound/outbound traffic, current connection count, local forwarded port, and proxy start time.
+
+The plugin tries `/stats` first and **falls back to `/status`** if the relay server hasn't been upgraded yet, so an outdated backend never breaks the panel.
+
+> Deploy these updated files to your relay server (e.g. via `dsh-update-server` deployment): `src/routes/tunnel.js` and `src/tunnel-service.js`. Then restart the relay service.
+
+## Remote Access Performance
+
+A common reason remote (external-tunnel) access feels slower than LAN: DSH's first screen fires many concurrent requests (JS/CSS / API / WebSocket), while frp's default work-connection pool (`poolCount`) is too small, so frpc repeatedly logs `work connection pool is full, discarding` — connections get dropped, queued and retried, making the initial page spin for a long time.
+
+This plugin optimizes it by:
+
+- **Larger frpc pool**: it injects `poolCount = 20` into each `[[proxies]]` of the generated `frpc.toml` (override with env `DSH_FRPC_POOL_COUNT`);
+- **Server-side match**: the `dsh-update-server` `deploy/frps.toml` template raises `transport.maxPoolCount` to `64` (takes effect after you deploy it to the relay server), so the server won't cap the client pool.
+
+---
+
 ## Screenshots
 
 ### Settings → Remote Control
@@ -109,7 +147,7 @@ So for users, **installing is one command** — no YAML editing, no manual file
 | qrcode | `lib/qrcode.js` | Inlined MIT QR generator (`qrcode-generator`), zero runtime deps |
 
 - **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).
+- **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; **DSH's native rail + hamburger drawer interactions are untouched**.
 
@@ -136,7 +174,7 @@ This command does three things automatically:
 
 The same works for other profiles — replace `web` with your profile name.
 
-> Local tarball testing: `dsh plugin --profile web add C:\path\to\feiyang666-dsh-mobile-remote-1.1.0.tgz`
+> Local tarball testing: `dsh plugin --profile web add C:\path\to\feiyang666-dsh-mobile-remote-1.4.1.tgz`
 
 ### 2. Restart and verify
 
@@ -165,6 +203,11 @@ Then restart the app.
 | Phone connects but shows 403 | dsh's trust fence: make sure the plugin is installed and dsh is started the supported way (`--patch` / profile patch overriding `webserver.host`) |
 | Device count stays 0 | The phone page must be opened once to start heartbeat; wait a few seconds and refresh |
 | QR won't scan | Confirm Remote Control is ON; use a camera app that supports QR |
+| External access blocked by a full-screen password page | That's the **remote access password gate** (v1.2.0+). Enter the correct password set locally under Settings → Remote Control → Remote Access Password; if forgotten, reset it on the host machine |
+| Remote loading still spins for a long time | Make sure the relay server's frps has `transport.maxPoolCount = 64` applied (`deploy/frps.toml`) and restart frps; re-enable external access once to rebuild the tunnel (`DSH_FRPC_POOL_COUNT` defaults to 20) |
+| Panel shows a red **"外网隧道鉴权失败"** error | frpc's `auth.token` doesn't match the frps server's `auth.token`. Sync the relay `.env`'s `FRP_TOKEN` with `/www/server/frps/frps.toml`'s `auth.token`, restart frps + the relay service, then toggle external access off and on |
+| External tunnel shows **"连接中"** but never turns online | frpc is retrying after a disconnect; open the panel's **查看 frpc 日志** to see the exact reason (server down / port blocked / token mismatch) |
+| A yellow banner warns **FRP_TOKEN 仍是占位符** | The relay `.env` still uses a placeholder `FRP_TOKEN`; it must be replaced with the real value matching frps.toml or the tunnel can never come up (502) |
 
 ---
 

package/README.zh.md

@@ -23,12 +23,50 @@
 - **连接二维码**：自动生成 `http://<局域网IP>:<端口>` 的二维码，手机相机 / 浏览器扫码即连；
 - **开启 / 关闭开关**：一键切换 webserver 监听地址（`0.0.0.0` ↔ `127.0.0.1`），经 dsh 官方 HMR 热重载**无需重启服务**；
 - **当前连接的设备数量**：移动端心跳上报，实时统计在线设备数；
+- **远程访问密码门禁**（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` 占位符时显示黄色警告条；隧道持续心跳保活，让中转端在线状态真实可靠；
 - 局域网地址列表、手机访问地址、配置位置一目了然。
 
 **核心卖点：纯命令行用户无需安装桌面端。** 官方 CLI 出于安全拒绝 `--host 0.0.0.0`，但本插件通过 profile 的 `cordis.patch.yml`（或 `--patch <overlay>`）写入 `webserver.host: 0.0.0.0`——这正是桌面端「移动端远程控制」开关的实现方式。手机与电脑共享同一个 dsh 后端进程与同一份 `~/.dsh` 数据，**会话列表、历史记录、工作区、设置全部天然双向同步，无需任何数据复制**。
 
 ---
 
+## 远程访问密码（可自定义，通用自托管）
+
+为了让「远程（外网隧道）访问」更安全，插件内置**远程访问密码门禁**：
+
+- 在 **设置 → 远程控制** 面板的「远程访问密码」卡片中，管理员可**在本机设置 / 修改 / 清除**一个密码；
+- 设置后，任何**通过外网隧道（`*.dsh.xxx.top`，HTTPS 反代）**访问本机 DSH 的浏览器，进入页面时都会被全屏密码页拦截，**必须输入正确密码**才能使用；本机（`127.0.0.1`）与局域网直连访问不受影响，保证管理员始终能正常管理与修复；
+- **密码完全存储在插件本地**（`~/.dsh/plugins/dsh-mobile-remote/config.json`），只保存 `scrypt` 哈希 + 随机盐，**绝不落盘明文**，校验使用 `timingSafeEqual` 防时序攻击，登录带失败次数限制防爆破。
+
+> **关键设计：完全本地、不依赖任何中转后端。** 无论你是否使用本项目自带的 `dsh-update-server` 中转服务，还是自建其它 frp / 中转方案，密码机制都能直接使用——它对任意「远程 HTTPS 访问」生效，与中转服务解耦。
+
+---
+
+## 中转服务端（dsh-update-server）接口
+
+插件外网隧道状态使用中转服务器的**成员端**接口（无需管理员登录）：
+
+- `GET /api/tunnel/status` — 基础成员状态（名称 / 在线 / 端口 / 最后心跳）；
+- `GET /api/tunnel/stats` — **成员隧道实时统计**（本次新增，需升级中转服务端）：含基础字段，并带 **frps 实时详情** —— 今日上行 / 下行流量、当前连接数、本地转发端口、隧道启动时间。
+
+插件会**先请求 `/stats`，后端未升级时自动回退到 `/status`**，所以旧后端不会导致面板异常。
+
+> 需将以下文件部署到你的中转服务器并重启服务：`src/routes/tunnel.js`、`src/tunnel-service.js`。
+
+## 远程访问性能优化
+
+远程（外网隧道）访问比内网慢的常见根因是：DSH 首屏会同时发起大量并发请求（JS/CSS / API / WebSocket），而 frp 隧道默认的工作连接池（`poolCount`）过小，导致 frpc 反复报 `work connection pool is full, discarding`，大量连接被丢弃、排队重试，表现为首页一直转圈。
+
+本插件做了以下优化：
+
+- **frpc 连接池调大**：生成的 `frpc.toml` 为每个 `[[proxies]]` 注入 `poolCount = 20`（可用环境变量 `DSH_FRPC_POOL_COUNT` 覆盖）；
+- **服务端配套**：`dsh-update-server` 的 `deploy/frps.toml` 模板将 `transport.maxPoolCount` 调大到 `64`（需部署到中转服务器后生效），避免服务端限制客户端连接池。
+
+---
+
 ## 界面预览
 
 ### 设置 → 远程控制
@@ -109,7 +147,7 @@ dsh --profile web --patch remote-control.patch.yml
 | qrcode | `lib/qrcode.js` | 内联 MIT QR 生成器（`qrcode-generator`），零运行时依赖 |
 
 - **开关**：`POST /__dsh_remote/toggle` → 写入 / 移除 profile `cordis.patch.yml` 的 `webserver` 覆盖块 → dsh `watchUserPatches`（Cordis HMR）热重载 webserver 行重新监听。
-- **设备数**：移动端注入 JS 每 30s 心跳上报，host 维护活跃设备表（90s 过期）。
+- **设备数**：移动端注入 JS 每 30s 心跳上报，host 维护活跃设备表（90s 过期）。每次心跳会上报完整设备元数据（屏幕 / 视口 / DPR / 网络 / 当前页面 / 语言 / 平台），设置面板的设备行可展开查看。
 - **二维码**：`GET /__dsh_remote/qr?url=...` 返回 SVG。
 - **移动端适配**：`tapIndex` 注入移动端 CSS/JS，composer 输入栏窄屏换行、选择器限宽、iOS 输入框 16px 防缩放；**不破坏 DSH 原生 rail + 汉堡抽屉交互**。
 
@@ -136,7 +174,7 @@ dsh plugin --profile web add @feiyang666/dsh-mobile-remote
 
 其它 profile 同理，把 `web` 换成你的 profile 名即可（如 `dsh plugin --profile headless add ...`）。
 
-> 想用本地 tarball 测试：`dsh plugin --profile web add C:\path\to\feiyang666-dsh-mobile-remote-1.1.0.tgz`
+> 想用本地 tarball 测试：`dsh plugin --profile web add C:\path\to\feiyang666-dsh-mobile-remote-1.4.1.tgz`
 
 ### 2. 重启并验证
 
@@ -165,6 +203,11 @@ dsh plugin --profile web remove @feiyang666/dsh-mobile-remote
 | 手机能访问但显示 403 | dsh 的信任围栏：请确认本插件已安装、且以官方支持的方式启动（`--patch` / profile patch 覆盖 `webserver.host`） |
 | 设备数为 0 | 手机端页面需打开过才会心跳上报；等待几秒刷新 |
 | 二维码扫不出来 | 确认「远程控制」已开启；相机应用需支持扫码 |
+| 外网访问被全屏密码页拦住 | 这是**远程访问密码门禁**（v1.2.0+）。管理员在本机「设置 → 远程控制 → 远程访问密码」输入正确密码即可进入；忘记密码需在本机重新设置 |
+| 远程访问仍转圈很慢 | 确认中转服务器 frps 已应用 `transport.maxPoolCount = 64`（`deploy/frps.toml`），并重启 frps；重新开启一次外网访问以重建隧道（`DSH_FRPC_POOL_COUNT` 默认 20） |
+| 面板红色提示「外网隧道鉴权失败」 | frpc 的 `auth.token` 与 frps 服务端不一致。请将中转 `.env` 的 `FRP_TOKEN` 与 `/www/server/frps/frps.toml` 的 `auth.token` 改成完全相同，重启 frps 与中转服务后，关闭再重新开启外网访问 |
+| 外网隧道一直「连接中」不见好 | frpc 在断线后自动重连；点面板上的「查看 frpc 日志」看真实原因（服务器宕机 / 端口被墙 / token 不匹配） |
+| 黄色警告条提示「FRP_TOKEN 仍是占位符」 | 中转 `.env` 的 `FRP_TOKEN` 还是占位符，必须改成与 frps.toml 一致的真实值，否则隧道永远起不来（502） |
 
 ---
 

package/RELEASE_NOTES.md

@@ -1,6 +1,6 @@
-# dsh-mobile-remote v1.1.0
+# dsh-mobile-remote v1.4.1
 
-**DeepSeek Harness 移动端远程控制插件** —— 在 Web UI 设置页内置「远程控制」：连接二维码、一键开关、在线设备数，让手机通过局域网访问并操控电脑上的 DeepSeek Harness。
+**DeepSeek Harness 移动端远程控制插件** —— 在 Web UI 设置页内置「远程控制」：连接二维码、一键开关、在线设备数，让手机通过局域网访问并操控电脑上的 DeepSeek Harness。本版聚焦**外网隧道真实状态诊断**：不再"假在线"，token 鉴权失败 / 断线重连一目了然。
 
 ## 安装方式
 
@@ -10,39 +10,42 @@ dsh plugin --profile web add @feiyang666/dsh-mobile-remote
 
 安装完成后**重启 dsh web 服务**，打开 `http://127.0.0.1:3080` → **设置 → 远程控制** 即可使用。
 
-## 本版更新（v1.1.0）
+## 本版更新（v1.4.1）
 
-> 本版本在 v1.0.0（移动端输入栏适配）基础上新增完整的**远程控制能力**，并从「纯前端注入」升级为「Host + Client 双面插件」。
+### 🚦 外网隧道真实状态判定（核心）
 
-### 设置页「远程控制」面板（新增）
+之前插件把「frpc 进程存活」误判为「隧道在线」——frpc 即使登录被拒、隧道从未建立，面板也显示绿色「在线」（打开链接却是 502）。本版彻底修复：
 
-- **连接二维码**：自动生成 `http://<局域网IP>:<端口>` 的二维码，手机相机 / 浏览器扫码即连
-- **开启 / 关闭开关**：一键切换 webserver 监听地址（`0.0.0.0` ↔ `127.0.0.1`），经 dsh 官方 HMR 热重载**无需重启服务**
-- **当前连接的设备数量**：移动端心跳上报，实时统计在线设备数
-- 局域网地址列表、手机访问地址、配置位置一目了然
+- **启动探测**：开启外网时读 frpc 日志，确认 `start proxy success` 隧道真正建立才算 `online`；
+- **轮询复查**：`/status` 每 5s 复查日志——断线降级「连接中」（自动重连中）、token 不匹配降级「出错」，重连成功后自动恢复；
+- **明确报错**：前端红色「出错」徽标 + 错误卡直接展示 frpc 真实原因（如 `token in login doesn't match token from configuration`），并附解决指引；
+- **一键重试**：出错状态点开关即可 kill 旧进程重新绑定。
 
-### 纯命令行启动支持（新增）
+### 🔁 隧道持续心跳保活
 
-- 官方 CLI 出于安全拒绝 `--host 0.0.0.0`，但本插件通过 profile 的 `cordis.patch.yml`（或 `--patch <overlay>`）写入 `webserver.host: 0.0.0.0`——**命令行用户无需安装桌面端**
-- 与桌面端「移动端远程控制」开关实现方式完全一致
+- 隧道在线期间每 60s 向中转端上报心跳，`last_seen` 保持新鲜；
+- 停止隧道时主动上报 `offline`，配合后端在线判定让管理端 / 面板实时反映真实状态。
 
-### Host API（新增）
+### ⚠️ FRP_TOKEN 占位符检测
 
-- `/__dsh_remote/status`：监听地址 / 端口 / LAN IP / 开关状态 / 在线设备数 / 配置位置
-- `/__dsh_remote/toggle`：写入 / 移除 profile patch（幂等，重复操作不产生重复块）
-- `/__dsh_remote/heartbeat`：移动端设备心跳上报（90s 过期）
-- `/__dsh_remote/qr`：连接二维码 SVG（内联 MIT QR 生成器，零运行时依赖）
+- 中转端新增 `frpTokenWarning` 字段；插件面板检测到服务器 `.env` 的 `FRP_TOKEN` 仍是占位符时，显示黄色警告条并说明会导致隧道 502。
 
-### 移动端输入栏适配（保留）
+### 🗂 DSH 状态卡默认折叠
 
-- composer 输入栏窄屏下自动换行分排，选择模型 / 选择安全模式不再粘连
-- 选择器限宽防溢出，按钮触控目标 ≥ 40px
-- iOS 输入框字号 ≥ 16px 防止聚焦自动缩放
+- 折叠态只显示摘要行（会话 / 工作区 / 插件 / 模型数），点击标题展开详情，节省面板空间。
+
+### 🐛 修复
+
+- 修复设置页空白崩溃（`status` 首次渲染为 `null` 时的守卫缺失）。
+
+## 后端配套（dsh-update-server）
+
+外网隧道详情、真实在线判定依赖中转端新接口（`/api/tunnel/stats`、`/heartbeat` 离线支持、成员端在线判定）。**旧后端不影响插件使用**：插件自动回退到 `/status` 接口。若要展示流量 / 连接数等丰富信息，请同步升级中转端（见 `dsh-update-server` 的 `DEPLOY_CHECKLIST.md`）。
 
 ## 已知事项
 
-- 开启后服务暴露到局域网，请仅在可信的家庭 / 办公网络使用，不要暴露到公网
-- 设备数统计依赖手机端页面打开后心跳上报，首次打开需等待几秒
+- 开启后服务暴露到公网，**请务必设置远程访问密码**，并仅在可信网络上使用
+- 外网隧道需确保服务器 `.env` 的 `FRP_TOKEN` 与 `/www/server/frps/frps.toml` 的 `auth.token` 完全一致，否则面板会明确提示鉴权失败
 
 ## 变更日志