dsh-mobile 0.5.0 → 0.5.1

package/docs/CLOUDFLARE_TUNNEL.en.md

@@ -1,5 +1,7 @@
 # Cloudflare named tunnel (a stable public hostname)
 
+[中文指南](CLOUDFLARE_TUNNEL.md)
+
 The built-in cloudflared provider runs in one of two modes, chosen in the panel under **Mobile access → Remote → cloudflared → Tunnel type**:
 
 | | Quick tunnel (default) | Named tunnel |
@@ -52,11 +54,11 @@ Moving to a fixed hostname means **an already paired phone must pair again**: a
 >
 > Scanning is optional: the full link (`https://your-domain/mobile-access/pair#instance=…&token=…`) can be copied to the phone and pasted, because the app accepts a complete link in its input field.
 
-The old remote entry in the device list will show **Address may have changed** or unreachable; delete it once the new pairing succeeds.
+The old address may show **Address may have changed** or temporarily unreachable before re-pairing. After pairing the same computer again, the app updates its existing remote-device record by device identity and keeps the custom name; there is no old entry to delete.
 
 ## Security boundary
 
-- The token is written only into the DSH Mobile private directory (`~/.dsh/mobile-access/remote/cloudflared/tunnel.json`, mode 0600) and is passed to `cloudflared` **only** through the `TUNNEL_TOKEN` environment variable, never on the command line, which any local process can read.
+- The token is written only into the DSH Mobile private directory (by default `$DSH_HOME/mobile-access/remote/cloudflared/tunnel.json`; Unix mode `0600`, restricted ACL on Windows) and is passed to `cloudflared` **only** through the `TUNNEL_TOKEN` environment variable, never on the command line.
 - The token is never returned to a browser or a phone. Panel status carries only whether it is configured, plus the hostname and port.
 - Behind the tunnel sits DSH Mobile's own authenticated gateway: the public hostname exposes that gateway, and DSH still requires paired-device credentials.
 - The plugin adds no system service, startup item, registry entry or PATH entry. Disabling the channel ends the process.
@@ -90,24 +92,17 @@ The old remote entry in the device list will show **Address may have changed** o
 
 ## Troubleshooting
 
-- **Stuck on "connecting"**: a named tunnel prints no banner, so it only becomes ready once the connector registers. Read the cloudflared output in the DSH log; the `CONNECTIVITY PRE-CHECKS` table says whether DNS, UDP/QUIC or TCP is the problem.
+- **Stuck on "connecting"**: the named tunnel becomes ready only after the connector registers with Cloudflare. Check cloudflared output in the DSH log and test DNS, UDP/QUIC and TCP reachability from the computer to a Cloudflare edge.
 - **Public access returns 1033**: Cloudflare believes no connector is healthy for that hostname. Check the tunnel shows Healthy in Zero Trust, and that its ingress port matches the panel.
 - **`cloudflared` reports `Unauthorized`, or the tunnel id does not exist**: the token belongs to a different tunnel, for example one that was deleted and recreated. Copy the token again.
-- **With a TUN or transparent proxy running (Clash, Mihomo, Clash Verge), the phone sticks on "Loading plugins" and retries forever.** This is a real failure that was measured, and it is easy to misread as a pairing or plugin problem:
-  - `cloudflared`'s connection to `region*.v2.argotunnel.com` has no dedicated rule, so it falls through to the catch-all `Match`/`MATCH` rule and is sent into a proxy node. The core's own API shows it plainly:
-    ```
-    cloudflared.exe -> region2.v2.argotunnel.com
-      rule=Match   chains=["<some airport node>","漏网之鱼"]   up/down = 103 MB / 2.1 MB
-    ```
-  - Downstream throughput then collapses to **8–100 KB/s**. The phone's DSH boot pulls a **4.5 MB** (compressed) boot bundle in one shot, the loader gives up, and the app shows "load, fail, retry".
-  - The same file took **0.2 s** on the LAN gateway, and **9.9 s / 454 KB/s** through the tunnel once routing was fixed — two orders of magnitude apart.
-  - Fix: route cloudflared and its edge domains directly. In Clash Verge's **global merge profile** (`profiles/Merge.yaml`, which subscription updates do not overwrite):
-    ```yaml
-    prepend-rules:
-      - PROCESS-NAME,cloudflared.exe,DIRECT
-      - DOMAIN-SUFFIX,argotunnel.com,DIRECT
-      - DOMAIN-SUFFIX,trycloudflare.com,DIRECT
-    ```
-    Then make cloudflared **reconnect**: hot-reloading the core does not migrate long-lived connections (use the panel's reconnect action, or toggle the provider off and on).
-  - To confirm it is this and not the phone: fetch the boot bundle from the computer with the same session and watch the rate. If the computer is just as slow, the phone and pairing are innocent.
+- **The phone stalls on "Loading plugins" or the remote page is slow while a TUN or transparent proxy is active**: check whether a catch-all rule sends `cloudflared` connections to `*.argotunnel.com` through a proxy node. This routing has caused slow boot-resource transfers before; it does not by itself indicate a pairing failure. This Clash-rule example is for Windows; on Linux, adapt the process name and syntax to your proxy client, and put direct-route rules before catch-all rules:
+
+  ```yaml
+  prepend-rules:
+    - PROCESS-NAME,cloudflared.exe,DIRECT
+    - DOMAIN-SUFFIX,argotunnel.com,DIRECT
+    - DOMAIN-SUFFIX,trycloudflare.com,DIRECT
+  ```
+
+  Then make cloudflared **reconnect** so existing connections take the new route (use the panel's reconnect action, or toggle the provider off and on). Compare the same resource through the LAN and remote entries. If the remote entry is also slow on the computer, inspect the computer-to-Cloudflare route first; if only the phone is slow, inspect its network.
 - **The domain still resolves to the old address**: after the nameserver change Cloudflare must move the zone from Pending to Active, and records in a pending zone are not served publicly.

package/docs/CLOUDFLARE_TUNNEL.md

@@ -1,5 +1,7 @@
 # Cloudflare 命名隧道（固定公网域名）
 
+[English guide](CLOUDFLARE_TUNNEL.en.md)
+
 内置的 cloudflared 通道有两种模式，在面板 **移动访问 → 远程 → cloudflared → 隧道类型** 中切换：
 
 | | 快速隧道（默认） | 命名隧道 |
@@ -52,11 +54,11 @@
 >
 > 不想扫码时，完整链接（`https://你的域名/mobile-access/pair#instance=…&token=…`）可以整条复制到手机上粘贴，App 的输入框接受完整链接。
 
-设备列表里原来那条远程记录会显示「地址可能已变化 / Address may have changed」或不可达，重新配对成功后删掉即可。
+旧地址在重新配对前可能显示「地址可能已变化」或暂不可达。重新配对同一台电脑后，App 会按设备标识更新原远程记录，保留自定义名称；无需删除它。
 
 ## 安全边界
 
-- 令牌只写入 DSH Mobile 私有目录（`~/.dsh/mobile-access/remote/cloudflared/tunnel.json`，权限 0600），并且**只**通过子进程环境变量 `TUNNEL_TOKEN` 传给 `cloudflared`，不出现在命令行里（本机任何进程都能读到命令行）。
+- 令牌只写入 DSH Mobile 私有目录（默认 `$DSH_HOME/mobile-access/remote/cloudflared/tunnel.json`；Unix 权限 `0600`，Windows 使用受限 ACL），并且**只**通过子进程环境变量 `TUNNEL_TOKEN` 传给 `cloudflared`，不出现在命令行里。
 - 令牌从不回传给浏览器或手机端；面板状态里只有「是否已配置」、域名和端口。
 - 隧道背后是 DSH Mobile 自己的认证网关：公网主机名只暴露该网关，DSH 本体仍然需要配对设备凭据。
 - 插件不会创建系统服务、开机启动项、注册表项或 PATH 项；关闭通道即结束进程。
@@ -90,24 +92,17 @@
 
 ## 排错
 
-- **连接一直停在「正在连接」**：命名隧道没有横幅，只有 connector 真正注册后才算就绪。查看 DSH 日志里 cloudflared 的输出；预检表（`CONNECTIVITY PRE-CHECKS`）会指出是 DNS、UDP/QUIC 还是 TCP 不通。
+- **连接一直停在「正在连接」**：命名隧道只有在 connector 向 Cloudflare 注册后才显示就绪。检查 DSH 日志中的 cloudflared 输出，以及本机到 Cloudflare 边缘的 DNS、UDP/QUIC 和 TCP 连通性。
 - **公网访问返回 1033**：Cloudflare 认为该主机名没有健康的 connector。确认隧道在 Zero Trust 里显示 Healthy，且 ingress 指向的端口与面板一致。
 - **`cloudflared` 报 `Unauthorized` 或隧道 ID 不存在**：令牌与控制台里的隧道不匹配（例如隧道被删除后重建）。重新复制令牌。
-- **本机开着 TUN/透明代理（Clash、Mihomo、Clash Verge 等）：手机端会卡在「正在加载插件」并反复重试。** 这是实测到过的一类真实故障，症状很容易被误判成配对或插件问题：
-  - `cloudflared` 到 `region*.v2.argotunnel.com` 的连接没有任何专属规则，于是落到兜底的 `Match`/`MATCH` 规则，被送进代理节点。用内核 API 看得很清楚：
-    ```
-    cloudflared.exe -> region2.v2.argotunnel.com
-      rule=Match   chains=["<某个机场节点>","漏网之鱼"]   up/down = 103 MB / 2.1 MB
-    ```
-  - 结果下行被压到 **8–100 KB/s**。而手机端 DSH 启动要一次拉 **4.5 MB**（压缩后）的 boot bundle，加载器等不到就报 `bundle script failed to load`，App 表现为「加载 → 失败 → 重试」。
-  - 同一份文件在局域网网关上是 **0.2 秒**，加上直连规则后走隧道是 **9.9 秒 / 454 KB/s** —— 差了两个数量级。
-  - 修法：让 cloudflared 与其边缘域名走直连。Clash Verge 的**全局扩展配置**（`profiles/Merge.yaml`，订阅更新不会覆盖）：
-    ```yaml
-    prepend-rules:
-      - PROCESS-NAME,cloudflared.exe,DIRECT
-      - DOMAIN-SUFFIX,argotunnel.com,DIRECT
-      - DOMAIN-SUFFIX,trycloudflare.com,DIRECT
-    ```
-    改完要让 cloudflared **重连**才会换路由：内核热重载不会迁移已建立的长连接（面板里点重连，或开关一次提供方）。
-  - 判断方法：如果手机端一直卡在加载插件，先在**本机**用同一份会话拉一次 boot bundle 看速率。若本机也很慢，就不是手机或配对的问题。
+- **手机卡在「正在加载插件」或远程页面明显慢，而本机开着 TUN/透明代理**：先检查 `cloudflared` 到 `*.argotunnel.com` 的连接是否被兜底规则送进代理节点。曾有这种路由导致启动资源传输很慢；它不等于配对失败。以下是 Windows 上 Clash 客户端的规则示例；Linux 的进程名与具体规则语法应按所用客户端调整，并让直连规则排在兜底规则前：
+
+  ```yaml
+  prepend-rules:
+    - PROCESS-NAME,cloudflared.exe,DIRECT
+    - DOMAIN-SUFFIX,argotunnel.com,DIRECT
+    - DOMAIN-SUFFIX,trycloudflare.com,DIRECT
+  ```
+
+  改完后让 cloudflared **重连**，使已建立的连接使用新路由（面板里点重连，或开关一次提供方）。对比同一资源经局域网与远程入口的加载速度；若远程入口在电脑上也慢，优先检查电脑到 Cloudflare 的路径，若只有手机慢，再检查手机网络。
 - **域名解析还是旧地址**：改完 NS 后 Cloudflare 需要把 zone 从 Pending 变为 Active；A/CNAME 在 zone 激活前不会对外生效。

package/docs/DSH_0.1.5_LAN.md

@@ -1,6 +1,6 @@
 # DeepSeek Harness 0.1.5 局域网验证
 
-本页记录 DSH Mobile 0.3.15 对 DeepSeek Harness 0.1.5 的局域网兼容性证据，以及该次实测没有覆盖的远程路径。
+本页是 DSH Mobile 0.3.15 对 DeepSeek Harness 0.1.5 的历史局域网验证记录，不表示当前版本或远程通道已通过同一测试。当前支持组合见[项目兼容性表](../README.md#兼容性)。
 
 ## 验证环境
 

package/docs/README.md

@@ -19,10 +19,10 @@
 
 | 文档 | 内容 |
 | --- | --- |
-| [DSH 0.1.5 局域网验证记录](DSH_0.1.5_LAN.md) | DSH Mobile 0.3.15 对 DeepSeek Harness 0.1.5 的局域网兼容验证 |
+| [DSH 0.1.5 局域网验证记录](DSH_0.1.5_LAN.md) | DSH Mobile 0.3.15 的历史局域网实测；当前版本组合请看[兼容性表](../README.md#兼容性) |
 
 ## 面向维护者 / Maintainer notes
 
 维护者文档面向改代码的人，**不随 npm 包发布**，只在仓库中阅读：
 
-- `docs/HANDOFF_SELF_HOSTED_FRP.md` —— 自建 FRP 的代码地图、错误码、安全边界与真机验证记录。
+- [自建 FRP 维护记录](HANDOFF_SELF_HOSTED_FRP.md) —— 0.4.6 开发时的代码地图、安全检查点与历史真机验证；当前使用步骤以本页上方的用户指南为准。

package/docs/SELF_HOSTED_FRP.en.md

@@ -20,7 +20,7 @@ Android app
 - **Domain mode**: use your own public domain; Caddy obtains and renews the certificate automatically.
 - **Public IPv4 mode**: use the VPS public IPv4 address directly. The plugin uses Certbot to request a roughly six-day Let's Encrypt IP certificate and installs a daily renewal timer. Documentation ranges such as `203.0.113.10`, private addresses, and other reserved addresses are rejected; enter a real routable public IP.
 
-The publicly trusted entry in this guide requires Android app 0.3.3 or later for custom remote origins. Self-signed passthrough requires the 0.4.6 app with remote CA pinning; older apps cannot use that entry and continue to work with LAN, cpolar, and Tailscale.
+The publicly trusted entry in this guide requires Android app 0.3.3 or later for custom remote origins. The separate self-signed TCP passthrough in the [existing-frps attachment guide](ATTACH_EXISTING_FRPS.en.md) is attach-only and requires the 0.4.6 or later app with remote CA pinning; older apps cannot use that entry and continue to work with LAN, cpolar, and Tailscale.
 
 ## Manual deployment vs automatic deployment
 
@@ -53,12 +53,14 @@ Public IPv4 mode also removes the corresponding Let's Encrypt IP certificate. Do
 On the VPS:
 
 ```bash
-sudo systemctl status dsh-mobile-frps.service caddy dsh-mobile-cert-renew.timer
+sudo systemctl status dsh-mobile-frps.service caddy
 sudo journalctl -u dsh-mobile-frps.service -u caddy -n 200 --no-pager
 sudo ss -lntp
-curl -vk https://PUBLIC_HOST/
+curl -v https://PUBLIC_HOST/mobile-access/discovery
 ```
 
+Only public IPv4 mode installs `dsh-mobile-cert-renew.timer`; in that mode, also run `sudo systemctl status dsh-mobile-cert-renew.timer`. Replace `PUBLIC_HOST` with your actual domain or public IPv4 address. Do not add `-k`: verify the public certificate as well as the response. Check the same address from an independent external network and confirm discovery reports this computer's installation identifier; success on the VPS alone does not prove the phone's network can reach it.
+
 On the computer, start with the plugin log at `$DSH_HOME/mobile-access/logs/dsh-mobile.log` (JSONL, 5 MB rotation, tokens and keys redacted) and the panel diagnostic report. Windows antivirus software can quarantine frpc; if it does, create the smallest possible exception for the verified component directory only.
 
 ## Limits
@@ -69,11 +71,6 @@ On the computer, start with the plugin log at `$DSH_HOME/mobile-access/logs/dsh-
 - VPS SSH targets currently cannot use IPv6.
 - The frps plaintext vhost must bind to `127.0.0.1`. The plugin rejects a publicly reachable plaintext port and reports readiness only after public discovery identifies the current computer.
 
-## Manual end-to-end checklist (before release)
+## Acceptance check
 
-- [x] Ubuntu IP mode: one-click redeploy on a VPS → public IPv4 ready → App discovery returned this computer (2026-09-03, Tencent Cloud).
-- [ ] Ubuntu domain mode: fresh VPS deployment → public domain ready → App pairing → send and receive messages.
-- [x] Existing Caddy coexistence: deploy into a Caddyfile containing an existing site and import line; verify user content is byte-for-byte preserved, the import occurs exactly once, and validation passes (2026-09-03, Tencent Cloud; concurrent writes use `flock`).
-- [x] Host-key change abort: an unconfirmed key set stops deployment/cleanup with `vps_host_key_mismatch` before network authentication (unit-test coverage plus full device fingerprint review).
-- [x] One-click cleanup: after deployment, services, files, timers, marked firewall rules, the owned system user, and the LE certificate were removed while the user's Caddy installation remained (2026-09-03, Tencent Cloud).
-- [x] Uninstall-script review: only DSH Mobile-owned paths and rules are touched (unit assertions plus device review).
+After deployment, check the certificate, public discovery endpoint, app pairing, and a live conversation on your own VPS and phone network. The repository's historical tests are recorded in the [self-hosted FRP handoff](HANDOFF_SELF_HOSTED_FRP.md); they cannot replace your own acceptance test.

package/docs/SELF_HOSTED_FRP.md

@@ -24,7 +24,7 @@
 - **域名模式**：公开地址是自己的域名，Caddy 自动申请并续期证书。
 - **公网 IPv4 模式**：公开地址直接是 VPS 公网 IPv4（例如你自己的 VPS 地址），插件用 Certbot 申请约 6 天有效的 Let's Encrypt IP 证书，并安装每日自动续期定时器。注意：文档示例地址（如 `203.0.113.10`）和内网、保留地址会被拒绝，必须填写真实可路由的公网 IP。
 
-本页的公开证书入口需要 Android App 0.3.3 或更高版本（远程自定义入口）。自签穿透档需要 0.4.6 Android App 固定远程 CA；旧版 App 不支持该档，仍可使用局域网、cpolar 和 Tailscale。
+本页的公开证书入口需要 Android App 0.3.3 或更高版本（远程自定义入口）。另见[接入既有 frps](ATTACH_EXISTING_FRPS.md)中的自签 TCP 穿透档：它仅适用于接入模式，需要 0.4.6 或更新的 Android App 固定远程 CA；旧版 App 不支持该档，仍可使用局域网、cpolar 和 Tailscale。
 
 ## 手动部署 vs 自动部署
 
@@ -57,12 +57,14 @@ SSH 用户、端口和私钥路径只保存在当前浏览器的 `localStorage`
 VPS 上：
 
 ```bash
-sudo systemctl status dsh-mobile-frps.service caddy dsh-mobile-cert-renew.timer
+sudo systemctl status dsh-mobile-frps.service caddy
 sudo journalctl -u dsh-mobile-frps.service -u caddy -n 200 --no-pager
 sudo ss -lntp
-curl -vk https://PUBLIC_HOST/
+curl -v https://PUBLIC_HOST/mobile-access/discovery
 ```
 
+只有公网 IPv4 模式会安装 `dsh-mobile-cert-renew.timer`，该模式另查 `sudo systemctl status dsh-mobile-cert-renew.timer`。将 `PUBLIC_HOST` 换成实际域名或公网 IPv4；不加 `-k`，以便同时验证公开证书。还应从独立外部网络检查同一地址，并确认 discovery 返回当前电脑的安装标识；只在 VPS 本机成功不代表手机网络可达。
+
 本机优先看插件日志（`$DSH_HOME/mobile-access/logs/dsh-mobile.log`，JSONL，超 5 MB 轮转，自动脱敏 Token 与密钥）与面板诊断报告。Windows 杀毒软件可能隔离 frpc；如确有拦截，只为已校验的组件目录设置最小范围例外。
 
 ## 限制
@@ -73,11 +75,6 @@ curl -vk https://PUBLIC_HOST/
 - VPS 的 SSH 目前不支持 IPv6 地址。
 - frps 明文 vhost 必须只监听 `127.0.0.1`；插件会拒绝公网可达的明文端口，并在公开发现接口确认是当前电脑后才显示“已就绪”。
 
-## 手动端到端验证清单（发布前）
+## 上线前验收
 
-- [x] Ubuntu IP 模式：已部署 VPS 上一键重部署 → 公网 IP 就绪 → App 级 discovery 返回当前电脑（2026-09-03，腾讯云实测）。
-- [ ] Ubuntu 域名模式：全新 VPS 一键部署 → 公网域名就绪 → App 远程配对 → 收发消息。
-- [x] 既有 Caddy 共存：在已有自有站点 + import 行的 Caddyfile 上部署，确认自有内容逐字节保留、import 恰好一行、validate 通过（2026-09-03，腾讯云实测；并发写有 flock 互斥）。
-- [x] 指纹变更中止：未确认密钥集合部署/清理直接 `vps_host_key_mismatch` 中止且零网络碰触（单元测试锁定；真机指纹全量核对通过）。
-- [x] 一键清理：部署后执行一键清理，服务、文件、定时器、标记防火墙规则、系统用户、LE 证书均已移除，自有 Caddy 本体保留（2026-09-03，腾讯云实测）。
-- [x] 卸载脚本审阅：仅触碰 DSH Mobile 拥有的路径与规则（单元测试断言 + 真机复核）。
+部署后，请在你的实际 VPS 与手机网络上检查证书、外网发现接口、App 配对和实时对话；本仓库的历史实测记录见[自建 FRP 交接记录](HANDOFF_SELF_HOSTED_FRP.md)，不能替代你自己的验收。

package/docs/SELF_HOSTED_ORIGIN.en.md

@@ -13,7 +13,7 @@ This provider appears under **Mobile Access → Remote → Self-hosted connectio
 - Separate LAN proxy: listen on the DSH computer's private IPv4, e.g. `192.168.50.10:3444`, and allow the proxy's actual direct source, e.g. `192.168.50.1/32`.
 - Only explicit loopback/RFC1918 IPv4 binds are supported. Wildcard, public and IPv6 binds are rejected. The port must be 1024–65535 and may not be 3443 (the LAN gateway) or 3080 (DSH's own WebServer); note that 3444 is also the cloudflared named tunnel's default forward port. Source CIDRs must be canonical private/loopback networks, at most 16; prefer a single-host /32. Forwarded headers do not determine source authorization.
 
-Select **Save and start backend**, then point the proxy at the displayed HTTP backend. **Never expose/port-forward that HTTP listener publicly**, and never bypass it by proxying to DSH 8080 (or its configured WebServer port) or the LAN 3443 gateway. HTTP between separate devices is suitable only for a trusted private network. Pairing, authentication, normalized-exact Host/Origin enforcement, CSRF, Secure cookies and WebSocket path policy remain active. Do not open the plain HTTP backend in a browser to verify it: cookies are marked `Secure`, so a browser discards them over `http://` and login or CSRF will fail with no visible reason.
+Select **Save and start backend**, then point the proxy at the displayed HTTP backend. **Never expose/port-forward that HTTP listener publicly**, and never bypass it by proxying to DSH's WebServer (default port 3080) or the LAN 3443 gateway. HTTP between separate devices is suitable only for a trusted private network. Pairing, authentication, normalized-exact Host/Origin enforcement, CSRF, Secure cookies and WebSocket path policy remain active. Do not open the plain HTTP backend in a browser to verify it: it only accepts requests proxied from the configured public HTTPS origin; direct access has the wrong Host, and its cookie/CSRF flow may fail.
 
 ## Proxy contract
 

package/docs/SELF_HOSTED_ORIGIN.md

@@ -15,7 +15,7 @@
 ```
 
 - **只有第一段允许暴露公网。HTTP 后端不能做公网端口映射。** HTTP 段仅适用于可信私网；局域网其他设备上的代理也会接触明文流量。
-- 后端不是裸 DSH：仍执行设备配对、认证、归一化后精确匹配的 Host/Origin 校验、CSRF、Secure Cookie 和 WebSocket 路径策略。没有配对的访问不能直接进入 DSH。**不要用浏览器直接打开这个明文 HTTP 后端做验证**：Cookie 带 `Secure`，浏览器在 `http://` 下会丢弃它们，登录或 CSRF 会无提示失败。
+- 后端不是裸 DSH：仍执行设备配对、认证、归一化后精确匹配的 Host/Origin 校验、CSRF、Secure Cookie 和 WebSocket 路径策略。没有配对的访问不能直接进入 DSH。**不要用浏览器直接打开这个明文 HTTP 后端做验证**：它只支持由指定 HTTPS 公网地址代理的请求；直接打开时 Host 不匹配，Cookie 与 CSRF 流程也可能失效。
 - 不要把公网反代目标改成 DSH 的 WebServer 端口（默认 3080），也不要反代现有 LAN HTTPS 3443。新后端默认 3444，**明确拒绝 3443 和 3080**，并拒绝 1024 以下需要特权的端口。注意 3444 同时是 cloudflared 命名隧道的默认转发端口：同一时刻只有一个远程提供方能运行，但切换到本提供方时请确认该端口已释放。DSH 与 LAN 的原有设置不变。
 - 公网 TLS、证书续期、DNS、路由和代理由你管理。插件不会安装隧道组件、部署 VPS、修改代理/防火墙/路由器，也不会为该提供方发起公网探测。
 

package/lib/client.js

@@ -2792,6 +2792,48 @@ window.__ModuleLoader__.load({
 		function firstByClassSuffix(root, suffix) {
 			return Array.from(root.querySelectorAll("[class]")).find((element) => classToken(element, suffix));
 		}
+		/**
+		* Whether this composer is the landing hero rather than the composer of an open
+		* conversation. DSH marks the hero composer's root with a `_hero` class and drops
+		* it once a session owns the surface, which is the only difference available
+		* without the layout's session id.
+		*/
+		function composerIsLandingHero(composer, depth = 4) {
+			let node = composer;
+			for (let step = 0; step < depth && node !== null; step += 1) {
+				if (classToken(node, "_hero")) return true;
+				node = node.parentElement;
+			}
+			return false;
+		}
+		/** Resolve only identities published by the current conversation or selected session row. */
+		function resolveComposerSessionOrigin(composer, selectedRow, selectedRowToken) {
+			const conversationRoot = composer?.closest("[data-conversation-session]") ?? null;
+			const conversationId = conversationRoot?.getAttribute("data-conversation-session");
+			if (conversationRoot !== null && conversationId) return {
+				sessionRoot: conversationRoot,
+				sessionId: conversationId
+			};
+			const dedicatedRoot = composer?.closest("[data-dsh-mobile-session]") ?? null;
+			const dedicatedId = dedicatedRoot?.getAttribute("data-dsh-mobile-session");
+			if (dedicatedRoot !== null && dedicatedId) return {
+				sessionRoot: dedicatedRoot,
+				sessionId: dedicatedId
+			};
+			if (selectedRow === null) return {
+				sessionRoot: null,
+				sessionId: null
+			};
+			const identity = selectedRow.getAttribute("data-session-id") ?? selectedRow.getAttribute("aria-label") ?? selectedRow.textContent?.trim() ?? "";
+			return {
+				sessionRoot: selectedRow,
+				sessionId: `${selectedRowToken(selectedRow)}:${identity}`
+			};
+		}
+		/** An id-less non-hero composer still accepts App soft-keyboard line breaks, but not camera results. */
+		function activeSessionForSoftEnter(composer, sessionId) {
+			return sessionId !== null || composer !== null && composer.closest(".dshm-main") !== null && !composerIsLandingHero(composer);
+		}
 		/** Find the stock DSH application frame without mistaking a feature card for the shell. */
 		function resolveNativeMobileFrame(root, dedicatedCenter) {
 			if (dedicatedCenter !== void 0) return void 0;
@@ -2962,6 +3004,38 @@ window.__ModuleLoader__.load({
 		function drawerScrimVisible(sidebarCollapsed, overlayActive) {
 			return !sidebarCollapsed && overlayActive;
 		}
+		/** Let the stock page close one visible layer before Android navigates its WebView. */
+		function installStockMobileBack(view, current, actions) {
+			const onBack = (event) => {
+				if (!event.cancelable || event.defaultPrevented) return;
+				const layers = current();
+				if (layers === null) return;
+				if (layers.detailsOpen) {
+					event.preventDefault();
+					actions.closeDetails();
+				} else if (layers.drawerOpen) {
+					event.preventDefault();
+					actions.closeDrawer();
+				} else if (layers.mainPanelOpen) {
+					event.preventDefault();
+					actions.closeMainPanel();
+				}
+			};
+			view.addEventListener("dsh-mobile:native-back", onBack);
+			return () => {
+				view.removeEventListener("dsh-mobile:native-back", onBack);
+			};
+		}
+		function stockLayoutBackControl(value) {
+			return typeof value === "object" && value !== null ? value : void 0;
+		}
+		/** Whether the stock layout can return from a selected main panel. */
+		function stockMainPanelOpen(value) {
+			const layout = stockLayoutBackControl(value);
+			if (typeof layout?.selectPanel !== "function" || typeof layout.panelInfo?.getSnapshot !== "function") return false;
+			const snapshot = layout.panelInfo.getSnapshot();
+			return typeof snapshot === "object" && snapshot !== null && typeof snapshot.activePanelId === "string";
+		}
 		/** Only a known on-screen keyboard in an active App composer may change Enter into a line break. */
 		function isSoftKeyboardEnterLineBreak(event, context) {
 			if (context.nativeState?.imeVisible !== true || context.nativeState.noHardwareKeyboard !== true || !context.editable || !context.activeSession || context.commandMenuOpen || context.recentlyComposing) return false;
@@ -3009,7 +3083,7 @@ window.__ModuleLoader__.load({
 			return !current.disposed && origin.generation === current.generation && origin.href === current.href && origin.composer !== null && current.composerConnected && origin.composer === current.composer && origin.sessionRoot !== null && origin.sessionRoot === current.sessionRoot && origin.sessionId !== null && origin.sessionId === current.sessionId;
 		}
 		/** Add mobile semantics without replacing feature trees. */
-		function installNativeMobileSurface() {
+		function installNativeMobileSurface(backServices) {
 			document.documentElement.classList.add("dsh-native-mobile-active");
 			const browserLanguages = navigator.languages.length > 0 ? navigator.languages : [navigator.language];
 			const language = resolveNativeMobileLanguage(document.documentElement.lang, browserLanguages);
@@ -3106,27 +3180,15 @@ window.__ModuleLoader__.load({
 			const sessionTokens = /* @__PURE__ */ new WeakMap();
 			let nextSessionToken = 0;
 			const currentSessionOrigin = () => {
-				const dedicatedRoot = boundComposer?.closest("[data-dsh-mobile-session]") ?? null;
-				const dedicatedId = dedicatedRoot?.getAttribute("data-dsh-mobile-session");
-				if (dedicatedRoot !== null && typeof dedicatedId === "string" && dedicatedId !== "") return {
-					sessionRoot: dedicatedRoot,
-					sessionId: dedicatedId
-				};
 				const selectedRow = document.querySelector("[role=\"treeitem\"][aria-selected=\"true\"]");
-				if (selectedRow === null) return {
-					sessionRoot: null,
-					sessionId: null
-				};
-				let token = sessionTokens.get(selectedRow);
-				if (token === void 0) {
-					token = `stock-${String(++nextSessionToken)}`;
-					sessionTokens.set(selectedRow, token);
-				}
-				const identity = selectedRow.getAttribute("data-session-id") ?? selectedRow.getAttribute("aria-label") ?? selectedRow.textContent?.trim() ?? "";
-				return {
-					sessionRoot: selectedRow,
-					sessionId: `${token}:${identity}`
-				};
+				return resolveComposerSessionOrigin(boundComposer, selectedRow, (row) => {
+					let token = sessionTokens.get(row);
+					if (token === void 0) {
+						token = `stock-${String(++nextSessionToken)}`;
+						sessionTokens.set(row, token);
+					}
+					return token;
+				});
 			};
 			const mediaRequestContext = () => {
 				const session = currentSessionOrigin();
@@ -3472,7 +3534,7 @@ window.__ModuleLoader__.load({
 				disposeEnterBinding = editor === null || composerCard === null ? void 0 : bindComposerSoftEnter(editor, () => ({
 					nativeState: window.__DSH_MOBILE_NATIVE__ === void 0 ? null : window.__DSH_MOBILE_KEYBOARD_STATE__,
 					editable: editor.isConnected && editor.getAttribute("contenteditable") === "true" && editor.getAttribute("aria-disabled") !== "true" && editor.getAttribute("aria-haspopup") !== "menu" && composerCard.getAttribute("aria-busy") !== "true",
-					activeSession: currentSessionOrigin().sessionId !== null,
+					activeSession: activeSessionForSoftEnter(composerCard, currentSessionOrigin().sessionId),
 					commandMenuOpen: composerCard.querySelector("[data-trigger-menu],button[aria-haspopup=\"listbox\"][aria-expanded=\"true\"]") !== null
 				}));
 			};
@@ -3621,6 +3683,33 @@ window.__ModuleLoader__.load({
 				if (sidebar?.dataset.open === "true") toggle?.click();
 			});
 			sync();
+			const stopStockBack = installStockMobileBack(window, () => {
+				if (frame?.isConnected !== true) return null;
+				const lastColumn = frame.style.gridTemplateColumns.trim().split(/\s+/).at(-1);
+				return {
+					detailsOpen: overlayQuery.matches && lastColumn !== void 0 && lastColumn !== "" && lastColumn !== "0px" && lastColumn !== "0",
+					drawerOpen: overlayQuery.matches && sidebarRoot?.isConnected === true && toggle?.isConnected === true && !classToken(sidebarRoot, "_collapsed"),
+					mainPanelOpen: stockMainPanelOpen(backServices.getLayout())
+				};
+			}, {
+				closeDetails: () => {
+					const layout = stockLayoutBackControl(backServices.getLayout());
+					if (typeof layout?.closeRightbar !== "function") return;
+					const sidebarRight = backServices.getSidebarRight();
+					if (typeof sidebarRight === "object" && sidebarRight !== null) {
+						const control = sidebarRight;
+						if (typeof control.isExpanded === "function" && typeof control.toggleExpanded === "function" && control.isExpanded()) control.toggleExpanded();
+					}
+					layout.closeRightbar();
+				},
+				closeDrawer: () => {
+					toggle?.click();
+				},
+				closeMainPanel: () => {
+					const layout = stockLayoutBackControl(backServices.getLayout());
+					if (typeof layout?.selectPanel === "function") layout.selectPanel(null);
+				}
+			});
 			const disposeTaskWatcher = installTaskCompletionWatcher({
 				completionFallback: false,
 				label: (kind, sessionLabel) => kind === "done" ? {
@@ -3633,6 +3722,7 @@ window.__ModuleLoader__.load({
 			});
 			return () => {
 				disposed = true;
+				stopStockBack();
 				disposeTaskWatcher();
 				mediaRequestGeneration += 1;
 				mediaPickerAbortController.abort();
@@ -3737,6 +3827,64 @@ window.__ModuleLoader__.load({
 		function parseMobileRemoteProvider(value) {
 			return value === "cpolar" || value === "cloudflared" || value === "frp" || value === "origin" ? value : "tailscale";
 		}
+		/**
+		* Set a surface's visibility; opening a page or overlay brings it to the front.
+		* @param container - the registered surface element.
+		* @param open - whether to show it.
+		*/
+		function setMobileSurfaceOpen(container, open) {
+			container.hidden = !open;
+			if (open && container.isConnected && (container.dataset.dshMobileSurfacePlacement === "page" || container.dataset.dshMobileSurfacePlacement === "overlay")) container.parentElement?.append(container);
+		}
+		function visibleBackLayer(view, element) {
+			if (!element.isConnected || element.hidden || element.closest("[hidden],[inert],[aria-hidden=\"true\"]") !== null) return false;
+			const style = view.getComputedStyle(element);
+			return style.display !== "none" && style.visibility !== "hidden" && element.getClientRects().length > 0;
+		}
+		/**
+		* Consume page-level surfaces and dismissible DSH overlays before layout navigation.
+		* @param view - the page window receiving the native Back request.
+		* @param page - the current DSH document.
+		* @param blocked - feedback for a foreground layer without a safe close action.
+		* @returns a disposer for the capture listener.
+		*/
+		function installMobileNativeBack(view, page, blocked) {
+			const onBack = (event) => {
+				if (!event.cancelable || event.defaultPrevented) return;
+				const claim = () => {
+					event.preventDefault();
+					event.stopImmediatePropagation();
+				};
+				const surface = [...page.querySelectorAll("[data-dsh-mobile-surface-placement=\"page\"], [data-dsh-mobile-surface-placement=\"overlay\"]")].filter((element) => visibleBackLayer(view, element)).at(-1);
+				if (surface !== void 0) {
+					setMobileSurfaceOpen(surface, false);
+					claim();
+					return;
+				}
+				const layers = [...page.querySelectorAll("[role=\"dialog\"][aria-modal=\"true\"], [role=\"menu\"]")].filter((element) => visibleBackLayer(view, element));
+				const top = layers.at(-1);
+				if (top === void 0) return;
+				claim();
+				if (top.getAttribute("role") === "dialog") {
+					const wrapper = top.parentElement;
+					const mask = wrapper?.firstElementChild;
+					const maskStyle = mask === void 0 || mask === null ? void 0 : view.getComputedStyle(mask);
+					if (wrapper?.getAttribute("role") === "presentation" && wrapper.children.length === 2 && wrapper.lastElementChild === top && mask?.tagName === "DIV" && mask.getAttribute("aria-hidden") === "true" && mask.isConnected && !mask.hidden && maskStyle?.display !== "none" && maskStyle?.visibility !== "hidden" && mask.getClientRects().length > 0) {
+						mask.click();
+						return;
+					}
+				} else if (top.getAttribute("data-menu-material") === "translucent" && layers.filter((layer) => layer.getAttribute("role") === "menu").length === 1) {
+					page.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+					return;
+				}
+				blocked();
+			};
+			const capture = { capture: true };
+			view.addEventListener("dsh-mobile:native-back", onBack, capture);
+			return () => {
+				view.removeEventListener("dsh-mobile:native-back", onBack, capture);
+			};
+		}
 		const queuedDefinitions = [];
 		let queuedLegacyMount;
 		if (typeof window !== "undefined" && window.dshMobile === void 0) window.dshMobile = {
@@ -3757,6 +3905,18 @@ window.__ModuleLoader__.load({
 		function selectedMobileControlLocale() {
 			return selectMobileControlLocale(document.documentElement.lang, navigator.languages?.length ? navigator.languages : [navigator.language]);
 		}
+		/**
+		* Guidance when an open third-party layer has no safe close action.
+		* @param locale - current Mobile UI language.
+		* @returns localized guidance.
+		*/
+		function mobileBackBlockedMessage(locale) {
+			return {
+				en: "Close the open panel first.",
+				it: "Chiudi prima il pannello aperto.",
+				zh: "请先关闭当前弹层。"
+			}[locale];
+		}
 		/** Remount one plugin-owned surface when DSH changes the document language. */
 		function installDshLanguageBoundSurface(install) {
 			let locale = selectedMobileControlLocale();
@@ -7880,6 +8040,9 @@ window.__ModuleLoader__.load({
 				shellLayer().append(node);
 				window.setTimeout(() => node.remove(), 2600);
 			};
+			const stopNativeBack = installMobileNativeBack(window, document, () => {
+				toast(mobileBackBlockedMessage(selectedMobileControlLocale()));
+			});
 			const materializeNativeFile = (value) => {
 				if (typeof value !== "object" || value === null || !("base64" in value) || !("name" in value)) return value;
 				const candidate = value;
@@ -8012,6 +8175,7 @@ window.__ModuleLoader__.load({
 					return registerUniqueDisposable(surfaces, surfaceIds, surface.id, () => {
 						const container = element("section");
 						container.dataset.dshMobileSurface = surface.id;
+						container.dataset.dshMobileSurfacePlacement = surface.placement;
 						container.hidden = surface.placement === "page" || surface.placement === "overlay";
 						container.style.cssText = surface.placement === "page" || surface.placement === "overlay" ? "position:absolute;inset:0;overflow:auto;background:var(--dsw-alias-bg-layer-1,#fff);padding:16px;pointer-events:auto" : "pointer-events:auto";
 						const host = () => surface.placement === "page" || surface.placement === "overlay" ? shellLayer() : surfaceHost(surface.placement) ?? shellLayer();
@@ -8064,12 +8228,12 @@ window.__ModuleLoader__.load({
 						open: (surfaceId) => {
 							ensureCurrent();
 							const entry = surfaces.get(surfaceId);
-							if (entry !== void 0) entry.container.hidden = false;
+							if (entry !== void 0) setMobileSurfaceOpen(entry.container, true);
 						},
 						close: (surfaceId) => {
 							ensureCurrent();
 							const entry = surfaces.get(surfaceId);
-							if (entry !== void 0) entry.container.hidden = true;
+							if (entry !== void 0) setMobileSurfaceOpen(entry.container, false);
 						},
 						toast: (message) => {
 							ensureCurrent();
@@ -8441,6 +8605,7 @@ window.__ModuleLoader__.load({
 			});
 			return () => {
 				disposed = true;
+				stopNativeBack();
 				stopEvents();
 				stopRefresh();
 				started = false;
@@ -8560,7 +8725,10 @@ window.__ModuleLoader__.load({
 						};
 					});
 					const removeCustom = installCustomAssets();
-					const removeSurface = installDshLanguageBoundSurface(installNativeMobileSurface);
+					const removeSurface = installDshLanguageBoundSurface(() => installNativeMobileSurface({
+						getLayout: () => ctx.get("layout"),
+						getSidebarRight: () => ctx.get("sidebarRight")
+					}));
 					return () => {
 						removeSettingsAction();
 						removeCustom();
@@ -8643,6 +8811,8 @@ window.__ModuleLoader__.load({
 		exports.handleMissingExtensionManifest = handleMissingExtensionManifest;
 		exports.inject = inject;
 		exports.installDshLanguageBoundSurface = installDshLanguageBoundSurface;
+		exports.installMobileNativeBack = installMobileNativeBack;
+		exports.mobileBackBlockedMessage = mobileBackBlockedMessage;
 		exports.normalizeDiagnosticOverall = normalizeDiagnosticOverall;
 		exports.normalizeDiagnosticStatus = normalizeDiagnosticStatus;
 		exports.parseMobileExtensionManifest = parseMobileExtensionManifest;
@@ -8653,6 +8823,7 @@ window.__ModuleLoader__.load({
 		exports.renderDiagnosticPayloadSafely = renderDiagnosticPayloadSafely;
 		exports.selectMobileControlLocale = selectMobileControlLocale;
 		exports.selectedMobileControlLocale = selectedMobileControlLocale;
+		exports.setMobileSurfaceOpen = setMobileSurfaceOpen;
 		exports.startExtensionChangeStream = startExtensionChangeStream;
 		exports.startLifecycleRefreshScheduler = startLifecycleRefreshScheduler;
 		exports.trustAuthenticatedGatewayConnection = trustAuthenticatedGatewayConnection;