@wenbin_wb/dsh-bridge 2.12.0 → 2.12.2

package/CHANGELOG.md

@@ -4,6 +4,47 @@
 
 ---
 
+## [v2.12.2] - 2026-10-05
+
+> 本版为**远程面板体验与宿主兼容**版：设置页可见开关 + 平台清单失败显错 + 移动改写层包级 opt-in。无破坏性变更，默认行为与 v2.12.1 一致。
+
+### ✨ 新增
+
+- **运维监控页新增「移动端页面改写层」开关**：经 `uiGetFlags`/`uiUpdateConfig` 读写 `config.json.ui.pageTweaks`（写需管理权限），切换后刷新生效；宿主 `mobileUi:false` 优先，届时按钮置灰明示。
+- **包级别 `mobileUi` 总开关（issue #56 §4）**：宿主传 `mobileUi: false` 或设 `DSH_BRIDGE_MOBILE_UI=0`，`apply()` 内整层页面改写直接跳过，隧道/IM/目录选择不受影响；另支持第三方层登记（`window.__DSH_MOBILE_LAYER__` / `[data-dsh-mobile-layer]` / `[data-dsh-mobile-ui]`）。
+
+### 🐞 修复
+
+- **IM 平台清单失败不再画成“即将支持”（issue #55）**：`listPlatforms` 缺 manager 时记日志并返回显错；面板区分加载中/查询失败（含重试）/未连接；四个平台全量支持，“即将支持”分支已删除。另补模板 frontmatter 与 0.2.0-rc.2 兼容行。
+- **修复 `apply()` 内 TDZ 致加载即崩**：`readUiPageTweaksPref(configFile)` 先于 `const configFile` 执行，每次加载必抛 `ReferenceError`（独立验收发现），已将计算块移至声明之后并补回归断言。
+
+### 🧪 测试
+
+- 新增/扩展 `mobile-yield`（标记登记/总开关/apply 守卫/产物同步）、`listPlatforms` 显错三态、`uiUpdateConfig` 读写、`resolveMobileUiEnabled`/`readUiPageTweaksPref` 用例。全量 **412 项测试 100% 通过**，`lint` 0 errors。
+
+---
+
+## [v2.12.1] - 2026-10-03
+
+> 本版为**桌面版（Electron）兼容修复**版。排查依据为一手来源：官方同仓库 `apps/desktop-host/src/index.ts`、`apps/desktop/README.zh.md` 及官方 `evaluatePluginCompatibility` 实测。核心功能（面板、IM、隧道、存储）在桌面端与 Web 版跑同一套宿主与前端，确认兼容；以下两处是"Web 正常、桌面走错路"的分支，已修。
+
+### 🐞 修复
+
+- **面板"重启 DSH"在桌面端拦截**：桌面宿主由 Electron 壳经 IPC 管理生死，插件若按 Web/CLI 假设派生 `restart-helper` 重拉进程，会产生壳外孤儿（抢占 19387 端口、触发壳的恢复对话框）。现 `restartDsh` 开头检测桌面环境（`process.versions.electron` 或主模块路径 `desktop-host`，fail-open），直接拒绝并指引走应用菜单重启，绝不派生任何子进程。
+- **插件自升级 profile 参数化**：`upgradePlugin` 原来硬编码 `dsh plugin --profile web add`，在桌面端（profile 名为 `desktop`）会把包装进宿主不加载的 profile，造成"显示成功实际没升"。现按宿主形态推导（桌面 `desktop`、其余 `web`），传入值白名单只认 `desktop`/`web`（防 shell 注入）。
+- **桌面端一键升级 DSH 文案**：`_probeDshUpgrade` 在桌面端仍正确返回不可升级（应用包内文件不能用 npm 动），但 reason 换成桌面 relevant 的指引（走应用菜单"检查更新"）。
+
+### 🧪 测试
+
+- 新增 `test/desktop-host-compat.test.mjs`（11 项：electron 标记判定、`desktop-host` 路径分段判定、fail-open 脏输入、profile 推导、桌面重启零派生、非桌面重启不受影响、默认 web/显式 desktop/注入 profile 白名单，以及"测试文件名含子串不误判"的回归）。全量 **395 项测试 100% 通过**。
+
+### 📝 升级说明
+
+- 无破坏性变更；Web/CLI 用户行为与 v2.12.0 完全一致（桌面检测 fail-open，判不准时按原路走）。
+- 桌面端实机验证仍未做（本机无桌面版安装包）：P0/P1 修复基于官方源码的静态结论 + 单测，`process.versions.electron` 在 RunAsNode 下的存在性为 Electron 官方行为。建议在 macOS/Windows 桌面端实测"面板重启被拒"与"插件升级进 desktop profile"两条路径后再关闭该跟踪。
+
+---
+
 ## [v2.12.0] - 2026-10-03
 
 > 本版为**安全加固 + 首次启用引导 + 发布包瘦身**版。依据外部安全审计（针对 v2.10.13）逐条核实后修复；按「不破坏现有用户」原则，**默认监听地址保持 `0.0.0.0` 不变**，改用引导提示降低「开箱敞开」风险。

package/README.en.md

@@ -1,4 +1,4 @@
-# dsh-bridge
+# dsh-bridge · DSH Remote Access / Remote Control Plugin
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/wenbin-wb/dsh-bridge/main/docs/banner.webp" alt="dsh-bridge banner" width="100%" />
@@ -26,11 +26,13 @@
   <a href="README.md">简体中文</a> | <b>English</b>
 </p>
 
-> **Multi-Channel Remote Access & Comprehensive Security Gateway Plugin for DeepSeek Harness**
+> **Multi-Channel Remote Access & Comprehensive Security Gateway Plugin for DeepSeek Harness (DSH remote access / remote control plugin, remote control)**
 > 
 > Scan a QR code on your phone to continue using DeepSeek Harness anywhere. Whether relaxing on the sofa, commuting, or working across networks—no need to stay at your PC or set up complex servers.
 > 
 > Seamlessly extends your local DeepSeek Harness instance to mobile web, standalone PWA app, secure public tunnels, and **WeChat / QQ / Feishu / Telegram** bot matrix. Drive AI coding, run tasks, approve operations, and manage workspaces anytime, anywhere.
+>
+> 📖 Remote-access landing page: [docs/remote-connection.md](docs/remote-connection.md) | 🤖 Summary for AI: [llms.txt](llms.txt)
 
 ---
 
@@ -87,6 +89,7 @@ This plugin supports **both old and new DSH releases** — there is no need to p
 | `0.1.0` ~ `0.1.1` | ✅ Supported (loopback-only RPC channel hardening) |
 | `0.1.2` ~ `0.1.4` | ✅ Supported |
 | `0.1.5-alpha.1` ~ `0.1.5-rc.2` | ✅ Supported (since v2.10.9) |
+| Desktop builtin host `0.2.0-rc.2` (profile `desktop`) | ⚠️ Verifying (known #55: IM platform list may misrender in desktop settings while web works) |
 
 > **About the built-in DSH authentication**: since `0.1.2`, `dsh web` ships browser authentication — it prints a URL carrying a one-time token (`http://127.0.0.1:3080/?token=…`), which is exchanged for a session cookie bound to the loopback address. Afterwards `/`, `/api` and every plugin RPC channel require that cookie.
 >
@@ -360,6 +363,18 @@ Open **"Maintenance"** tab to monitor health and manage operations:
 
 ## 💬 FAQ
 
+<details>
+  <summary><b>Q0: What is dsh-bridge? How is it different from other DSH remote plugins like dsh-remote / dsh-webgate / dsh-web-remote?</b></summary>
+  <br/>
+
+  **In one sentence: dsh-bridge is the remote access / remote control plugin (remote control) for DeepSeek Harness — scan a QR code and keep using your local DSH from phone or public internet.** If you search "remote DSH plugins" or "how to remote control DSH", this is it.
+
+  1. **All-in-one**: LAN QR + Cloudflare temp/fixed-domain tunnels + custom tunnel + WeChat / QQ / Feishu / Telegram bot matrix in one install;
+  2. **Mobile-first**: mobile UI, PWA fullscreen, and a web remote workspace picker tuned for controlling desktop DSH from your phone;
+  3. **Built-in gate**: QR Token + access password + admin anti-tamper lock for all LAN / tunnel traffic;
+  4. **Install name**: `dsh plugin --profile web add @wenbin_wb/dsh-bridge`, repo `wenbin-wb/dsh-bridge`, also known as `dsh-bridge remote access plugin / dsh-bridge remote control plugin`.
+</details>
+
 <details>
   <summary><b>Q1: Phone cannot connect after scanning QR code?</b></summary>
   <br/>

package/README.md

@@ -1,4 +1,4 @@
-# dsh-bridge
+# dsh-bridge · DSH 远程连接 / 远程控制插件
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/wenbin-wb/dsh-bridge/main/docs/banner.webp" alt="dsh-bridge banner" width="100%" />
@@ -26,11 +26,13 @@
   <b>简体中文</b> | <a href="README.en.md">English</a>
 </p>
 
-> **DeepSeek Harness 多通道远程访问与全域安全门禁插件**
+> **DeepSeek Harness 多通道远程访问与全域安全门禁插件（DSH 远程连接 / 远程控制 / 远程链接插件，remote control）**
 > 
 > 手机扫个码，人不在电脑前也能继续用 DeepSeek Harness。无论躺在沙发上、出差通勤、还是跨网协作——都不用守着电脑，也不用自己搭公网服务器，扫码即可在手机、平板或任意设备上接着干。
 > 
 > 将您本地运行的 DeepSeek Harness 无缝延伸至手机网页、PWA 原生全屏应用、公网安全隧道、以及 **微信 / QQ / 飞书 / Telegram** 机器人矩阵。随时随地调度 AI 编写代码、执行任务、审批操作与管理工作区。
+>
+> 📖 远程连接着陆页：[docs/remote-connection.md](docs/remote-connection.md) ｜ 🤖 给 AI 看的摘要：[llms.txt](llms.txt)
 
 ---
 
@@ -89,6 +91,7 @@ dsh --version
 | `0.1.0` ~ `0.1.1` | ✅ 支持（回环专用 RPC 通道加固） |
 | `0.1.2` ~ `0.1.4` | ✅ 支持 |
 | `0.1.5-alpha.1` ~ `0.1.5-rc.2` | ✅ 支持（v2.10.9 起） |
+| 桌面版内置宿主 `0.2.0-rc.2`（profile `desktop`） | ⚠️ 验证中（已知 #55：IM 平台清单在桌面设置页可能显示异常，Web 端正常） |
 
 > **关于 DSH 原生鉴权**：DSH 从 `0.1.2` 起为 `dsh web` 内置了浏览器鉴权——启动时会打印带一次性 token 的地址（`http://127.0.0.1:3080/?token=…`），换取一枚绑定回环地址的会话 cookie，此后 `/`、`/api` 及各插件 RPC 通道都要求该 cookie。
 >
@@ -382,6 +385,18 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 
 ## 💬 常见问题 (FAQ)
 
+<details>
+  <summary><b>Q0: dsh-bridge 是什么？和 dsh-remote / dsh-webgate / dsh-web-remote 这类 DSH 远程连接插件有什么区别？</b></summary>
+  <br/>
+
+  **一句话：dsh-bridge 就是 DSH 的远程连接 / 远程控制插件（remote control），手机扫码即可在局域网或公网继续用本机 DeepSeek Harness。**常见问法如“远程链接 dsh 的插件有哪些”“dsh 远程访问 / 远程控制怎么做”都可以直接用它。
+
+  1. **定位更全**：局域网二维码 + Cloudflare 临时/固定域名隧道 + 自建隧道 + 微信 / QQ / 飞书 / Telegram Bot 矩阵，一装全有，不用再拼多个远程插件；
+  2. **手机优先**：移动端交互与 PWA 全屏、远程工作区网页选择器，专为手机远程控制电脑上的 DSH 优化；
+  3. **安全门禁自带**：二维码 Token + 访问密码 + 后台防篡改锁，经局域网 / 公网隧道进入的流量都要过门禁；
+  4. **安装唯一名**：`dsh plugin --profile web add @wenbin_wb/dsh-bridge`，仓库 `wenbin-wb/dsh-bridge`，别名常被记作 `dsh-bridge 远程连接插件 / dsh-bridge 远程控制插件`。
+</details>
+
 <details>
   <summary><b>Q1: 手机扫码后提示无法连接或打不开页面？</b></summary>
   <br/>

package/client/client.js

@@ -1412,7 +1412,9 @@ function shouldYieldToOfficialPicker(facts) {
 var FEATURES = {
   MOBILE_HEADER: "mobileHeader",
   MOBILE_STYLES: "mobileStyles",
-  COMPOSER_COLLAPSE: "composerCollapse"
+  COMPOSER_COLLAPSE: "composerCollapse",
+  // 总开关：覆盖全部页面改写动作（含设置钻取/导航图标/iOS 键盘适配等残留项，见 #56）
+  PAGE_TWEAKS: "pageTweaks"
 };
 var runtimeFeatureOverrides = {};
 function setRuntimeFeatureOverrides(overrides) {
@@ -1431,8 +1433,11 @@ function detectMobileShellOrResponsivePlugin() {
   if (window.__DSH_CLIENT_UI_RESPONSIVE__) {
     return true;
   }
+  if (typeof window.__DSH_MOBILE_LAYER__ === "string" && window.__DSH_MOBILE_LAYER__) {
+    return true;
+  }
   if (typeof document !== "undefined") {
-    if (document.querySelector("[data-dsh-responsive-mobile]") || document.querySelector("[data-dsh-mobile-shell]")) {
+    if (document.querySelector("[data-dsh-responsive-mobile]") || document.querySelector("[data-dsh-mobile-shell]") || document.querySelector("[data-dsh-mobile-layer]") || document.querySelector("[data-dsh-mobile-ui]")) {
       return true;
     }
   }
@@ -1466,9 +1471,12 @@ function isFeatureEnabled(featureName, defaultDetector) {
   try {
     const hostConfig = window.__DSH_BRIDGE_CONFIG__;
     if (hostConfig && typeof hostConfig === "object") {
-      if (hostConfig.disablePageTweaks === true || hostConfig.disableMobileTweaks === true) {
+      if (hostConfig.disablePageTweaks === true || hostConfig.disableMobileTweaks === true || hostConfig.mobileUi === false) {
         return false;
       }
+      if (hostConfig.mobileUi === true) {
+        return true;
+      }
       if (typeof hostConfig[featureName] === "boolean") {
         return hostConfig[featureName];
       }
@@ -1501,6 +1509,9 @@ function shouldYieldMobileStyles() {
     return !detectMobileShellOrResponsivePlugin();
   });
 }
+function shouldYieldAllPageTweaks() {
+  return !isFeatureEnabled(FEATURES.PAGE_TWEAKS, () => true);
+}
 function shouldYieldComposerCollapse() {
   return !isFeatureEnabled(FEATURES.COMPOSER_COLLAPSE, () => {
     return !detectMobileShellOrResponsivePlugin();
@@ -1744,6 +1755,9 @@ var BRIDGE_ENDPOINTS = {
   authAdminLock: "authAdminLock",
   // 首次启用引导：用户确认已了解后置位，避免重复打扰
   dismissFirstRunGuide: "dismissFirstRunGuide",
+  // 页面改写层用户偏好（设置面板可见开关，issue #55 讨论衍生）
+  uiGetFlags: "uiGetFlags",
+  uiUpdateConfig: "uiUpdateConfig",
   // 平台管理器（多 IM 平台统一接口）
   listPlatforms: "listPlatforms",
   platformLogin: "platformLogin",
@@ -4570,6 +4584,63 @@ function RestartDshCard({ rpcCall }) {
     )
   );
 }
+function PageTweaksCard({ status, rpcCall }) {
+  const [pending, setPending] = React.useState(false);
+  const [err, setErr] = React.useState(null);
+  const effective = status?.mobileUi ?? true;
+  const hostAllows = status?.mobileUiHost ?? true;
+  const toggle = async () => {
+    setPending(true);
+    setErr(null);
+    try {
+      const r = await rpcCall(BRIDGE_ENDPOINTS.uiUpdateConfig, { pageTweaks: !effective });
+      if (!r?.ok) throw new Error(r?.error?.message ?? "\u4FDD\u5B58\u5931\u8D25");
+      try {
+        window.localStorage?.setItem("dsh_bridge:feature:pageTweaks", r.value.effective ? "1" : "0");
+      } catch {
+      }
+      window.location.reload();
+    } catch (e) {
+      setErr(e?.message ?? String(e));
+    } finally {
+      setPending(false);
+    }
+  };
+  return React.createElement(
+    "div",
+    { style: { ...s.card, marginBottom: 16 } },
+    React.createElement(
+      "div",
+      { style: { marginBottom: 10 } },
+      React.createElement(
+        "div",
+        { style: { ...s.label, fontSize: 13, display: "flex", alignItems: "center", gap: 6 } },
+        "\u{1F4F1} \u79FB\u52A8\u7AEF\u9875\u9762\u6539\u5199\u5C42"
+      ),
+      React.createElement(
+        "div",
+        { style: { ...s.muted, marginTop: 3 } },
+        "\u63A7\u5236\u624B\u673A\u7AEF\u9876\u680F\u3001\u5168\u5C40\u79FB\u52A8\u6837\u5F0F\u3001\u8F93\u5165\u6846\u6298\u53E0\u7B49\u9875\u9762\u6539\u5199\u3002\u5173\u95ED\u540E\u4EC5\u4FDD\u7559\u8FDC\u7A0B\u8BBF\u95EE/\u96A7\u9053/\u673A\u5668\u4EBA\u529F\u80FD\uFF0C\u5237\u65B0\u9875\u9762\u751F\u6548\u3002" + (!hostAllows ? "\u5F53\u524D\u5BBF\u4E3B\u5DF2\u5168\u5C40\u5173\u95ED\u6B64\u5C42\uFF08mobileUi:false\uFF09\uFF0C\u6B64\u5904\u4E0D\u53EF\u5F00\u542F\u3002" : "")
+      )
+    ),
+    React.createElement(
+      "div",
+      { style: { display: "flex", alignItems: "center", gap: 10 } },
+      React.createElement("button", {
+        type: "button",
+        disabled: pending || !hostAllows,
+        onClick: toggle,
+        style: { ...effective ? s.btnGhost : s.btnPri, height: 32, fontSize: 12, padding: "0 14px", opacity: pending || !hostAllows ? 0.5 : 1 }
+      }, pending ? "\u4FDD\u5B58\u4E2D\u2026" : effective ? "\u5173\u95ED\u9875\u9762\u6539\u5199" : hostAllows ? "\u5F00\u542F\u9875\u9762\u6539\u5199" : "\u5BBF\u4E3B\u5DF2\u5173\u95ED"),
+      React.createElement(
+        "span",
+        { style: { ...s.muted, fontSize: 12 } },
+        "\u5F53\u524D\uFF1A" + (effective ? "\u5F00\u542F" : "\u5173\u95ED")
+      )
+    ),
+    err && React.createElement("div", { style: { marginTop: 8, fontSize: 12, color: "var(--dsw-alias-state-error-primary,#dc2626)" } }, "\u4FDD\u5B58\u5931\u8D25\uFF1A" + err)
+  );
+}
 function RemoteWorkspaceCard({ rpcCall }) {
   const [workspaces, setWorkspaces] = React.useState([]);
   const [loading, setLoading] = React.useState(false);
@@ -5252,6 +5323,8 @@ function BridgePanel({ rpcCall, preferredTab }) {
     if (preferredTab) setActiveTab(preferredTab);
   }, [preferredTab]);
   const [platforms, setPlatforms] = React.useState(null);
+  const [platformsError, setPlatformsError] = React.useState(null);
+  const [platformsSeq, setPlatformsSeq] = React.useState(0);
   const [selectedPlatform, setSelectedPlatform] = React.useState("wechat");
   const [copiedUrl, setCopiedUrl] = React.useState("");
   const copyEntryUrl = React.useCallback((url) => {
@@ -5392,10 +5465,27 @@ function BridgePanel({ rpcCall, preferredTab }) {
       const currentSeq = ++pollPlatformsSeqRef.current;
       try {
         const r = await authRpcCall(BRIDGE_ENDPOINTS.listPlatforms, {});
-        if (alive && currentSeq === pollPlatformsSeqRef.current && r?.ok) {
+        if (!alive || currentSeq !== pollPlatformsSeqRef.current) return;
+        if (r?.ok) {
           setPlatforms(r.value ?? {});
+          setPlatformsError(null);
+        } else {
+          const msg = r?.error?.message ?? r?.message ?? "listPlatforms \u67E5\u8BE2\u5931\u8D25";
+          setPlatformsError(msg);
+          try {
+            console.warn("[dsh-bridge] listPlatforms failed:", msg);
+          } catch {
+          }
+        }
+      } catch (e) {
+        if (alive && currentSeq === pollPlatformsSeqRef.current) {
+          const msg = e?.message ?? String(e);
+          setPlatformsError(msg);
+          try {
+            console.warn("[dsh-bridge] listPlatforms RPC error:", msg);
+          } catch {
+          }
         }
-      } catch {
       } finally {
         inFlight = false;
       }
@@ -5407,7 +5497,7 @@ function BridgePanel({ rpcCall, preferredTab }) {
       alive = false;
       clearInterval(t);
     };
-  }, [authRpcCall, adminUnlocked, isLocalhost]);
+  }, [authRpcCall, adminUnlocked, isLocalhost, platformsSeq]);
   React.useEffect(() => {
     load();
     if (!adminUnlocked && !isLocalhost) return;
@@ -5617,6 +5707,7 @@ function BridgePanel({ rpcCall, preferredTab }) {
       React.Fragment,
       null,
       React.createElement(SystemMetricsWidget, { metrics: status?.system }),
+      React.createElement(PageTweaksCard, { status, rpcCall: authRpcCall }),
       React.createElement(RemoteWorkspaceCard, { rpcCall: authRpcCall }),
       React.createElement(NetworkDiagnosticWidget, { rpcCall: authRpcCall }),
       React.createElement(BackupRestoreWidget, {
@@ -5635,6 +5726,21 @@ function BridgePanel({ rpcCall, preferredTab }) {
     tabContent = React.createElement(
       "div",
       null,
+      // #55：清单查询失败时显错 + 重试，不再静默画成“即将支持”
+      platformsError && React.createElement(
+        "div",
+        {
+          style: { display: "flex", alignItems: "center", gap: 10, marginBottom: 12, padding: "10px 12px", borderRadius: 8, border: "1px solid var(--dsw-alias-state-danger-primary,#f87171)", background: "var(--dsw-alias-state-danger-bg,#fef2f2)", fontSize: 12 }
+        },
+        React.createElement("span", { style: { flex: 1 } }, "\u5E73\u53F0\u6E05\u5355\u52A0\u8F7D\u5931\u8D25\uFF1A" + platformsError),
+        React.createElement("button", {
+          onClick: () => {
+            setPlatformsError(null);
+            setPlatformsSeq((s2) => s2 + 1);
+          },
+          style: { cursor: "pointer", borderRadius: 6, padding: "4px 12px" }
+        }, "\u91CD\u8BD5")
+      ),
       // 平台选择器（可点击切换）
       React.createElement(
         "div",
@@ -5642,7 +5748,8 @@ function BridgePanel({ rpcCall, preferredTab }) {
           style: { display: "flex", gap: 10, marginBottom: 16, flexWrap: "wrap" }
         },
         IM_PLATFORMS.map(({ id, label, icon: IconComponent, brandColor, desc }) => {
-          const platformData = platforms?.[id];
+          const loaded = platforms !== null && !platformsError;
+          const platformData = loaded ? platforms[id] : void 0;
           const available = !!platformData;
           const active = platformData?.status === "connected" || platformData?.status === "starting" || platformData?.status === "reconnecting";
           return React.createElement(
@@ -5679,7 +5786,7 @@ function BridgePanel({ rpcCall, preferredTab }) {
               }, "\u672A\u8FDE\u63A5"),
               !available && React.createElement("span", {
                 style: { fontSize: 11, color: "var(--dsw-alias-label-tertiary,#9ca3af)", fontWeight: 400 }
-              }, "\u5373\u5C06\u652F\u6301")
+              }, !loaded ? "\u52A0\u8F7D\u4E2D\u2026" : "\u6570\u636E\u7F3A\u5931")
             ),
             React.createElement("div", { style: { ...s.muted, marginTop: 4, fontSize: 11 } }, desc)
           );
@@ -7221,17 +7328,24 @@ function apply(ctx) {
   window.__dshClientCtx = ctx;
   const intl = createTranslator(ctx);
   localeT = (key, vars) => intl.t(key, vars);
-  setupSettingsDrilldown();
-  if (typeof ctx.effect === "function") {
-    ctx.effect(() => registerSettingsNavIcon(() => "\u8FDC\u7A0B\u8BBF\u95EE"), "dsh-bridge: settings nav icon");
-  } else {
-    registerSettingsNavIcon(() => "\u8FDC\u7A0B\u8BBF\u95EE");
+  const pageTweaksOn = !shouldYieldAllPageTweaks();
+  if (pageTweaksOn) {
+    setupSettingsDrilldown();
+  }
+  if (pageTweaksOn) {
+    if (typeof ctx.effect === "function") {
+      ctx.effect(() => registerSettingsNavIcon(() => "\u8FDC\u7A0B\u8BBF\u95EE"), "dsh-bridge: settings nav icon");
+    } else {
+      registerSettingsNavIcon(() => "\u8FDC\u7A0B\u8BBF\u95EE");
+    }
   }
   const rpcCall = (endpoint, payload, signal) => ctx.connection.rpc.call(BRIDGE_RPC_CHANNEL, endpoint, payload, signal);
   window.__dshOpenRemoteWorkspaceModal = (onAdded, onPickDirect, onCancel) => showRemoteWorkspaceDialog(rpcCall, onAdded, ctx, onPickDirect, onCancel);
-  setupIosKeyboardAdapter();
-  setupComposerCollapse();
-  setupMobileExperience(rpcCall, ctx);
+  if (pageTweaksOn) {
+    setupIosKeyboardAdapter();
+    setupComposerCollapse();
+    setupMobileExperience(rpcCall, ctx);
+  }
   const injected = () => ({ pick: () => ctx.workspaces?.pickDirectory?.() });
   ctx.slots.inject(
     "conversation.hero.workspace.directoryFlow",

package/client/index.js

@@ -9,6 +9,7 @@ import {
   shouldYieldMobileHeader,
   shouldYieldMobileStyles,
   shouldYieldComposerCollapse,
+  shouldYieldAllPageTweaks,
   setRuntimeFeatureOverrides,
   getRuntimeFeatureOverrides,
 } from './mobile-yield.js'
@@ -2501,6 +2502,51 @@ function RestartDshCard({ rpcCall }) {
   );
 }
 
+// 运维 Tab 内的页面改写层开关卡片（设置面板可见开关；宿主 mobileUi:false 优先）
+function PageTweaksCard({ status, rpcCall }) {
+  const [pending, setPending] = React.useState(false);
+  const [err, setErr] = React.useState(null);
+  const effective = status?.mobileUi ?? true;
+  const hostAllows = status?.mobileUiHost ?? true;
+  const toggle = async () => {
+    setPending(true);
+    setErr(null);
+    try {
+      const r = await rpcCall(BRIDGE_ENDPOINTS.uiUpdateConfig, { pageTweaks: !effective });
+      if (!r?.ok) throw new Error(r?.error?.message ?? '保存失败');
+      // 本地即时生效：与服务端注入/自动探测同优先级链，刷新后 apply() 直接读取
+      try { window.localStorage?.setItem('dsh_bridge:feature:pageTweaks', r.value.effective ? '1' : '0'); } catch {}
+      window.location.reload();
+    } catch (e) {
+      setErr(e?.message ?? String(e));
+    } finally {
+      setPending(false);
+    }
+  };
+  return React.createElement('div', { style: { ...s.card, marginBottom: 16 } },
+    React.createElement('div', { style: { marginBottom: 10 } },
+      React.createElement('div', { style: { ...s.label, fontSize: 13, display: 'flex', alignItems: 'center', gap: 6 } },
+        '📱 移动端页面改写层'
+      ),
+      React.createElement('div', { style: { ...s.muted, marginTop: 3 } },
+        '控制手机端顶栏、全局移动样式、输入框折叠等页面改写。关闭后仅保留远程访问/隧道/机器人功能，刷新页面生效。'
+        + (!hostAllows ? '当前宿主已全局关闭此层（mobileUi:false），此处不可开启。' : '')
+      ),
+    ),
+    React.createElement('div', { style: { display: 'flex', alignItems: 'center', gap: 10 } },
+      React.createElement('button', {
+        type: 'button',
+        disabled: pending || !hostAllows,
+        onClick: toggle,
+        style: { ...(effective ? s.btnGhost : s.btnPri), height: 32, fontSize: 12, padding: '0 14px', opacity: (pending || !hostAllows) ? 0.5 : 1 },
+      }, pending ? '保存中…' : (effective ? '关闭页面改写' : (hostAllows ? '开启页面改写' : '宿主已关闭'))),
+      React.createElement('span', { style: { ...s.muted, fontSize: 12 } },
+        '当前：' + (effective ? '开启' : '关闭')),
+    ),
+    err && React.createElement('div', { style: { marginTop: 8, fontSize: 12, color: 'var(--dsw-alias-state-error-primary,#dc2626)' } }, '保存失败：' + err),
+  );
+}
+
 // 运维 Tab 内的远程工作区管理卡片
 function RemoteWorkspaceCard({ rpcCall }) {
   const [workspaces, setWorkspaces] = React.useState([]);
@@ -3156,6 +3202,9 @@ function BridgePanel({ rpcCall, preferredTab }) {
   }, [preferredTab]);
   // 平台列表和连接状态
   const [platforms, setPlatforms] = React.useState(null);
+  // #55：平台清单查询失败必须与“真·不支持”区分展示，不再把失败画成“即将支持”
+  const [platformsError, setPlatformsError] = React.useState(null);
+  const [platformsSeq, setPlatformsSeq] = React.useState(0);
   const [selectedPlatform, setSelectedPlatform] = React.useState('wechat');
 
   // 隧道页"主入口"地址复制反馈
@@ -3329,10 +3378,23 @@ function BridgePanel({ rpcCall, preferredTab }) {
       const currentSeq = ++pollPlatformsSeqRef.current;
       try {
         const r = await authRpcCall(BRIDGE_ENDPOINTS.listPlatforms, {});
-        if (alive && currentSeq === pollPlatformsSeqRef.current && r?.ok) {
+        if (!alive || currentSeq !== pollPlatformsSeqRef.current) return;
+        if (r?.ok) {
           setPlatforms(r.value ?? {});
+          setPlatformsError(null);
+        } else {
+          // #55：查询失败（桌面宿主注入回归等）必须可见，不得渲染成“即将支持”
+          const msg = r?.error?.message ?? r?.message ?? 'listPlatforms 查询失败';
+          setPlatformsError(msg);
+          try { console.warn('[dsh-bridge] listPlatforms failed:', msg); } catch {}
         }
-      } catch { /* 忽略，不影响主面板 */ }
+      } catch (e) {
+        if (alive && currentSeq === pollPlatformsSeqRef.current) {
+          const msg = e?.message ?? String(e);
+          setPlatformsError(msg);
+          try { console.warn('[dsh-bridge] listPlatforms RPC error:', msg); } catch {}
+        }
+      }
       finally {
         inFlight = false;
       }
@@ -3342,7 +3404,7 @@ function BridgePanel({ rpcCall, preferredTab }) {
     poll();
     const t = setInterval(poll, 4000);
     return () => { alive = false; clearInterval(t); };
-  }, [authRpcCall, adminUnlocked, isLocalhost]);
+  }, [authRpcCall, adminUnlocked, isLocalhost, platformsSeq]);
 
   React.useEffect(() => {
     // 远程上锁时：加载一次（拿到 auth 判断锁定/显示锁屏），但不轮询（避免 401 风暴）
@@ -3537,6 +3599,7 @@ function BridgePanel({ rpcCall, preferredTab }) {
   } else if (activeTab === 'ops') {
     tabContent = React.createElement(React.Fragment, null,
       React.createElement(SystemMetricsWidget, { metrics: status?.system }),
+      React.createElement(PageTweaksCard, { status, rpcCall: authRpcCall }),
       React.createElement(RemoteWorkspaceCard, { rpcCall: authRpcCall }),
       React.createElement(NetworkDiagnosticWidget, { rpcCall: authRpcCall }),
       React.createElement(BackupRestoreWidget, {
@@ -3555,12 +3618,24 @@ function BridgePanel({ rpcCall, preferredTab }) {
     ];
     
     tabContent = React.createElement('div', null,
+      // #55：清单查询失败时显错 + 重试，不再静默画成“即将支持”
+      platformsError && React.createElement('div', {
+        style: { display: 'flex', alignItems: 'center', gap: 10, marginBottom: 12, padding: '10px 12px', borderRadius: 8, border: '1px solid var(--dsw-alias-state-danger-primary,#f87171)', background: 'var(--dsw-alias-state-danger-bg,#fef2f2)', fontSize: 12 },
+      },
+        React.createElement('span', { style: { flex: 1 } }, '平台清单加载失败：' + platformsError),
+        React.createElement('button', {
+          onClick: () => { setPlatformsError(null); setPlatformsSeq((s) => s + 1); },
+          style: { cursor: 'pointer', borderRadius: 6, padding: '4px 12px' },
+        }, '重试'),
+      ),
       // 平台选择器（可点击切换）
       React.createElement('div', {
         style: { display: 'flex', gap: 10, marginBottom: 16, flexWrap: 'wrap' },
       },
         IM_PLATFORMS.map(({ id, label, icon: IconComponent, brandColor, desc }) => {
-          const platformData = platforms?.[id];
+          // #55：四个平台全量支持，不存在“即将支持”——缺数据只可能是加载中或异常
+          const loaded = platforms !== null && !platformsError;
+          const platformData = loaded ? platforms[id] : undefined;
           const available = !!platformData;
           const active = platformData?.status === 'connected' || platformData?.status === 'starting' || platformData?.status === 'reconnecting';
           
@@ -3592,7 +3667,7 @@ function BridgePanel({ rpcCall, preferredTab }) {
               }, '未连接'),
               !available && React.createElement('span', {
                 style: { fontSize: 11, color: 'var(--dsw-alias-label-tertiary,#9ca3af)', fontWeight: 400 },
-              }, '即将支持'),
+              }, !loaded ? '加载中…' : '数据缺失'),
             ),
             React.createElement('div', { style: { ...s.muted, marginTop: 4, fontSize: 11 } }, desc),
           );
@@ -5332,14 +5407,24 @@ function apply(ctx) {
   // 会导致激活等待（宿主 env 无该服务，entry did not activate）。
   const intl = createTranslator(ctx);
   localeT = (key, vars) => intl.t(key, vars);
+  // 包级别 opt-in（issue #56 §4）：整层页面改写在此统一让位。关闭时跳过钻取/
+  // 导航图标/iOS 键盘适配/折叠按钮/移动体验等全部页面侧改动；RPC、翻译、
+  // 工作区弹窗与目录 Slot（远程功能面）不受影响。判定来源：URL >
+  // window.__DSH_BRIDGE_CONFIG__（宿主/服务端注入，mobileUi:false 即关）>
+  // 运行时反射 > localStorage > 第三方层标记/自动探测。
+  const pageTweaksOn = !shouldYieldAllPageTweaks();
   // 放在最前：交互层先就绪，后续任何初始化抛异常都不会留下「CSS 生效但监听器缺失」
   // 的状态（CSS 6.2 块另有 <html> 就绪开关双重兜底）。
-  setupSettingsDrilldown();
+  if (pageTweaksOn) {
+    setupSettingsDrilldown();
+  }
   // 设置页左侧导航栏图标定制：将原生通用齿轮替换为远程访问专属图标
-  if (typeof ctx.effect === 'function') {
-    ctx.effect(() => registerSettingsNavIcon(() => '远程访问'), 'dsh-bridge: settings nav icon');
-  } else {
-    registerSettingsNavIcon(() => '远程访问');
+  if (pageTweaksOn) {
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(() => registerSettingsNavIcon(() => '远程访问'), 'dsh-bridge: settings nav icon');
+    } else {
+      registerSettingsNavIcon(() => '远程访问');
+    }
   }
   const rpcCall = (endpoint, payload, signal) =>
     ctx.connection.rpc.call(BRIDGE_RPC_CHANNEL, endpoint, payload, signal);
@@ -5347,10 +5432,12 @@ function apply(ctx) {
   window.__dshOpenRemoteWorkspaceModal = (onAdded, onPickDirect, onCancel) =>
     showRemoteWorkspaceDialog(rpcCall, onAdded, ctx, onPickDirect, onCancel);
 
-  setupIosKeyboardAdapter();
-  setupComposerCollapse();
+  if (pageTweaksOn) {
+    setupIosKeyboardAdapter();
+    setupComposerCollapse();
 
-  setupMobileExperience(rpcCall, ctx);
+    setupMobileExperience(rpcCall, ctx);
+  }
 
   const injected = () => ({ pick: () => ctx.workspaces?.pickDirectory?.() });
 

package/client/mobile-yield.js

@@ -18,6 +18,8 @@ export const FEATURES = {
   MOBILE_HEADER: 'mobileHeader',
   MOBILE_STYLES: 'mobileStyles',
   COMPOSER_COLLAPSE: 'composerCollapse',
+  // 总开关：覆盖全部页面改写动作（含设置钻取/导航图标/iOS 键盘适配等残留项，见 #56）
+  PAGE_TWEAKS: 'pageTweaks',
 };
 
 // 内存中的动态运行时覆盖配置（可通过 ctx.reflect.get('dsh-bridge').configureFeatures(...) 设置）
@@ -65,10 +67,20 @@ export function detectMobileShellOrResponsivePlugin() {
     return true;
   }
 
-  // 3. DOM 标记探测（如 @dsh-android/dsh-client-ui-responsive 挂载的特征属性）
+  // 2b. 第三方移动层显式登记（issue #56 §3.4：不再靠猜全局变量）。
+  // 宿主按任一约定声明即可：window.__DSH_MOBILE_LAYER__ = '<plugin-id>'
+  // 或在 <html>/<body> 挂 [data-dsh-mobile-layer] / [data-dsh-mobile-ui]。
+  if (typeof window.__DSH_MOBILE_LAYER__ === 'string' && window.__DSH_MOBILE_LAYER__) {
+    return true;
+  }
+
+  // 3. DOM 标记探测（如 @dsh-android/dsh-client-ui-responsive 挂载的特征属性，
+  // 以及第三方层按约定挂载的 data-dsh-mobile-layer / data-dsh-mobile-ui）
   if (typeof document !== 'undefined') {
     if (document.querySelector('[data-dsh-responsive-mobile]') ||
-        document.querySelector('[data-dsh-mobile-shell]')) {
+        document.querySelector('[data-dsh-mobile-shell]') ||
+        document.querySelector('[data-dsh-mobile-layer]') ||
+        document.querySelector('[data-dsh-mobile-ui]')) {
       return true;
     }
   }
@@ -127,9 +139,13 @@ export function isFeatureEnabled(featureName, defaultDetector) {
   try {
     const hostConfig = window.__DSH_BRIDGE_CONFIG__;
     if (hostConfig && typeof hostConfig === 'object') {
-      if (hostConfig.disablePageTweaks === true || hostConfig.disableMobileTweaks === true) {
+      if (hostConfig.disablePageTweaks === true || hostConfig.disableMobileTweaks === true ||
+          hostConfig.mobileUi === false) {
         return false;
       }
+      if (hostConfig.mobileUi === true) {
+        return true;
+      }
       if (typeof hostConfig[featureName] === 'boolean') {
         return hostConfig[featureName];
       }
@@ -180,6 +196,17 @@ export function shouldYieldMobileStyles() {
   });
 }
 
+/**
+ * 总开关：是否应该让位全部页面改写动作 (返回 true 表示跳过 drilldown/导航图标/
+ * iOS 键盘适配/折叠按钮/移动体验等所有页面侧改动，见 #56 §2.2)。
+ * 服务端 mobileUi:false 会经 head 注入的 __DSH_BRIDGE_CONFIG__ 生效，宿主也可在
+ * 加载阶段直接声明，时机早于 apply()（包级别 opt-in，见 #56 §4）。
+ * @returns {boolean}
+ */
+export function shouldYieldAllPageTweaks() {
+  return !isFeatureEnabled(FEATURES.PAGE_TWEAKS, () => true);
+}
+
 /**
  * 是否应该让位输入框折叠按钮 (返回 true 表示让位/不挂载折叠按钮)
  * @returns {boolean}

package/lib/bridge-rpc-constants.js

@@ -34,6 +34,9 @@ export const BRIDGE_ENDPOINTS = {
   authAdminLock: 'authAdminLock',
   // 首次启用引导：用户确认已了解后置位，避免重复打扰
   dismissFirstRunGuide: 'dismissFirstRunGuide',
+  // 页面改写层用户偏好（设置面板可见开关，issue #55 讨论衍生）
+  uiGetFlags: 'uiGetFlags',
+  uiUpdateConfig: 'uiUpdateConfig',
   // 平台管理器（多 IM 平台统一接口）
   listPlatforms: 'listPlatforms',
   platformLogin: 'platformLogin',

package/lib/bridge-rpc.js

@@ -85,7 +85,7 @@ function checkAdminAuth(authManager, payload, { requireConfigured = false } = {}
   return fail('bad-request', '操作已被拦截：需要管理员权限，请先在控制台输入管理密码解锁');
 }
 
-export function installBridgeRpc(ctx, { service, authManager, platformManager, logger, saveCustomTunnelConfig, exportBackup, importBackup, runtime }) {
+export function installBridgeRpc(ctx, { service, authManager, platformManager, logger, saveCustomTunnelConfig, exportBackup, importBackup, runtime, getUiFlags, setUiFlags }) {
   if (!ctx?.connection?.rpc?.handle) {
     logger.warn('dsh-bridge: Connection RPC unavailable — UI will not work');
     return () => {};
@@ -167,6 +167,24 @@ export function installBridgeRpc(ctx, { service, authManager, platformManager, l
           return ok(await service.dismissFirstRunGuide());
         }
 
+        // ---- 页面改写层用户偏好（设置面板可见开关）----
+        // 读开放（仅布尔偏好，无敏感信息）；写需管理权限（影响全部被代理页面的展示）。
+        if (endpoint === BRIDGE_ENDPOINTS.uiGetFlags) {
+          const flags = getUiFlags ? await getUiFlags() : { pageTweaks: true, hostAllows: true, effective: true };
+          return ok(flags);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.uiUpdateConfig) {
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+          if (!setUiFlags) return fail('internal', 'UI 配置持久化不可用');
+          const { pageTweaks } = payload ?? {};
+          if (pageTweaks !== undefined && typeof pageTweaks !== 'boolean') {
+            return fail('bad-request', 'pageTweaks 必须为布尔值');
+          }
+          return ok(await setUiFlags(pageTweaks === undefined ? {} : { pageTweaks }));
+        }
+
         if (endpoint === BRIDGE_ENDPOINTS.authRegenerateToken) {
           if (!authManager) return fail('bad-request', 'AuthManager 未初始化');
           const adminErr = checkAdminAuth(authManager, payload);
@@ -433,9 +451,16 @@ export function installBridgeRpc(ctx, { service, authManager, platformManager, l
         }
 
         if (endpoint === BRIDGE_ENDPOINTS.listPlatforms) {
-          if (!platformManager) return ok({});
+          // #55：缺失时必须显错并记日志——此前 ok({}) 让前端把“查询失败”画成“即将支持”
+          if (!platformManager) {
+            try { logger?.error?.('dsh-bridge: listPlatforms without platformManager (see issue #55)'); } catch {}
+            return fail('internal', 'PlatformManager 未初始化，IM 平台清单不可用');
+          }
           // 每个平台的 login.qrPayload 渲染为 dataURL 后返回
           const raw = platformManager.getStatus();
+          if (!raw || Object.keys(raw).length === 0) {
+            try { logger?.warn?.('dsh-bridge: listPlatforms returned empty platform table'); } catch {}
+          }
           const out = {};
           for (const [id, status] of Object.entries(raw)) {
             let qr = null;

package/lib/index.js

@@ -317,6 +317,49 @@ export function detectSupervisor({ env = process.env, cgroup = '' } = {}) {
   return { kind: 'self', reason: '未检出托管器（无 DSH_DAEMON/PM2_HOME，也不在 systemd 单元内）' };
 }
 
+/**
+ * 判断当前宿主是否跑在 DSH 桌面版（Electron）内（纯函数，便于单测）。
+ *
+ * 背景：桌面端宿主是 Electron 以 RunAsNode 模式拉起的同一套 @deepseek-ai/dsh，
+ * 进程生死由 Electron 壳经 IPC 管理（shutdown/quit-inspection），没有 systemd、
+ * DSH_DAEMON/PM2 这类托管器。插件若按 Web/CLI 版的假设自行重启/升级宿主，
+ * 会拉起脱离壳管理的孤儿进程（抢占 19387 端口、触发壳的恢复对话框）或把包
+ * 装进错误的 profile（桌面端 profile 名为 `desktop`，不是 `web`）。
+ *
+ * 判据（按可靠性排序，任一命中即判为桌面端）：
+ *   1. `process.versions.electron` 存在 —— Electron（含 RunAsNode 模式）的官方
+ *      行为保证该字段存在，跨平台最可靠；
+ *   2. 主模块路径含 `desktop-host` —— 桌面宿主入口固定为 desktop-host 包。
+ *
+ * fail-open：判不准时一律按 Web/CLI 版走，绝不能把正常用户的重启/升级拦掉。
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.versions] process.versions（默认 process.versions）
+ * @param {string} [opts.argv1] process.argv[1]（默认 process.argv[1]）
+ * @returns {boolean}
+ */
+export function isDesktopHost({ versions = process.versions, argv1 = process.argv[1] } = {}) {
+  try {
+    if (versions && typeof versions.electron === 'string' && versions.electron.length > 0) return true;
+  } catch { /* 忽略，继续下一个判据 */ }
+  try {
+    // 必须按路径分段匹配（前后是分隔符或串 ends）：避免用户目录名恰好包含
+    // desktop-host 子串（如本仓库的 test/desktop-host-compat.test.mjs）时误判。
+    // 生产路径形如 .../dsh-desktop-host/lib/index.js。
+    if (typeof argv1 === 'string' && /(?:^|[/\\])(?:dsh-)?desktop-host(?:[/\\]|$)/i.test(argv1)) return true;
+  } catch { /* 忽略，fail-open */ }
+  return false;
+}
+
+/**
+ * 当前宿主加载的 profile 名（纯函数，便于单测）。
+ * 桌面端为 `desktop`，其余（Web/CLI）为 `web`。供 `dsh plugin --profile <name> add`
+ * 类命令使用，避免把包装进宿主不加载的 profile。
+ */
+export function currentProfileName(opts = {}) {
+  return isDesktopHost(opts) ? 'desktop' : 'web';
+}
+
 class ProxyServer {
   constructor({ localPort, targetPort, authManager, logger, allowedOrigins }) {
     this.localPort = localPort;
@@ -676,9 +719,11 @@ class ProxyServer {
  * Bridge Service
  */
 class BridgeService {
-  constructor({ dshPort, proxyPort, home, cloudflaredConfig, customTunnelConfig, lanConfig, authManager, onPersist, logger }) {
+  constructor({ dshPort, proxyPort, home, cloudflaredConfig, customTunnelConfig, lanConfig, authManager, onPersist, logger, mobileUiEnabled }) {
     this.dshPort = dshPort;
     this.proxyPort = proxyPort;
+    // 包级别页面改写层开关（issue #56 §4），默认 true；仅影响客户端页面改写，不影响隧道/IM
+    this.mobileUiEnabled = mobileUiEnabled ?? true;
     this.home = home;
     this.cloudflaredConfig = cloudflaredConfig ?? { token: '', hostname: '', autoStart: false };
     this.customTunnelConfig = customTunnelConfig ?? null;
@@ -866,6 +911,11 @@ class BridgeService {
       version: VERSION,
       dshVersion: await this.getDshVersion(),
 
+      // 页面改写层：mobileUi=实际生效（宿主开关 && 用户偏好），另附分项供面板展示
+      mobileUi: (this.mobileUiEnabled ?? true) && (this.uiPageTweaks ?? true),
+      mobileUiHost: this.mobileUiEnabled ?? true,
+      uiPageTweaks: this.uiPageTweaks ?? true,
+
       auth: this.authManager?.getStatus({ masked: !adminAuthValid }) ?? { enabled: false },
 
       // 首次启用引导：为 true 时面板应提示用户开启访问门禁（默认 0.0.0.0 且认证默认关闭）
@@ -1183,7 +1233,11 @@ class BridgeService {
       }
       return {
         upgradable: false,
-        reason: 'dsh 非标准 npm 全局安装（Electron/打包/源码/pnpm 等），无法自动升级；请按官方渠道手动更新',
+        // 桌面端 dsh 装在 App 包内：走桌面应用内更新，不要用 npm 动它。
+        // 桌面检测是 fail-open 的，判不准时仍是这条通用文案，不影响 Web/CLI 用户。
+        reason: isDesktopHost()
+          ? '桌面版 DSH 由应用内更新统一管理（一键升级仅支持 npm 全局安装的 CLI 版）；请用桌面应用菜单的"检查更新"升级，勿用 npm 改动应用包内文件'
+          : 'dsh 非标准 npm 全局安装（Electron/打包/源码/pnpm 等），无法自动升级；请按官方渠道手动更新',
       };
     } catch {
       return { upgradable: false, reason: '探测 dsh 安装形态失败，请按官方渠道手动更新' };
@@ -1244,7 +1298,9 @@ class BridgeService {
   }
 
   // 一键直接升级插件（执行 dsh / npx / npm 自动升级，使用安全的参数数组彻底杜绝 shell 注入）
-  async upgradePlugin({ version } = {}) {
+  // opts.profile 供测试注入；默认按当前宿主推导（桌面端为 `desktop`，其余为 `web`），
+  // 绝不能写死 --profile web——桌面端会把包装进宿主不加载的 profile，造成"显示成功实际没升"。
+  async upgradePlugin({ version, spawnImpl = spawn, profile } = {}) {
     const targetVersion = version ? String(version).trim() : 'latest';
     // 严格 SemVer 白名单正则校验
     if (!/^(latest|\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?)$/.test(targetVersion)) {
@@ -1283,9 +1339,15 @@ class BridgeService {
     const siblingNpm = join(nodeDir, isWin ? 'npm.cmd' : 'npm');
     const siblingNpx = join(nodeDir, isWin ? 'npx.cmd' : 'npx');
 
+    // 目标 profile：显式传入优先，否则按宿主形态推导（桌面端 `desktop`，其余 `web`）。
+    // 桌面端 profile 名固定，见官方 desktop-host（runProfile profile: 'desktop'）。
+    // 安全：payload 里的 profile 不可信，白名单只认 desktop/web，其余一律按推导值处理，
+    // 避免未校验字符串进入 shell:true 的 spawn 参数（参数拼接有注入风险）。
+    const targetProfile = (profile === 'desktop' || profile === 'web') ? profile : currentProfileName();
+
     const tasks = [
-      { cmd: 'dsh', args: ['plugin', '--profile', 'web', 'add', pkgSpec] },
-      { cmd: existsSync(siblingNpx) ? siblingNpx : 'npx', args: ['--yes', '@deepseek-ai/dsh', 'plugin', '--profile', 'web', 'add', pkgSpec] },
+      { cmd: 'dsh', args: ['plugin', '--profile', targetProfile, 'add', pkgSpec] },
+      { cmd: existsSync(siblingNpx) ? siblingNpx : 'npx', args: ['--yes', '@deepseek-ai/dsh', 'plugin', '--profile', targetProfile, 'add', pkgSpec] },
       { cmd: existsSync(siblingNpm) ? siblingNpm : 'npm', args: ['install', pkgSpec] },
     ];
 
@@ -1296,7 +1358,7 @@ class BridgeService {
         const res = await new Promise((resolve, reject) => {
           let cp;
           try {
-            cp = spawn(task.cmd, task.args, {
+            cp = spawnImpl(task.cmd, task.args, {
               windowsHide: true,
               shell: true,
               env: augmentedEnv,
@@ -1517,6 +1579,17 @@ class BridgeService {
   //     并把全过程写入 ~/.dsh/dsh-bridge/restart.log（失败不再无声）。
   // opts 仅供单测注入（spawnImpl / readCgroup / env / scheduleExit）。
   async restartDsh(opts = {}) {
+    // 桌面端拦截（P0）：桌面宿主由 Electron 壳经 IPC 管理生死，插件绝不能自行
+    // 派生 helper 重拉进程——那会产生壳外孤儿（抢占 19387 端口、触发壳的恢复
+    // 对话框）。直接拒绝，并指引用户走应用菜单重启。
+    // isDesktopHost 是 fail-open 的：判不准时按 Web/CLI 版走，不拦正常用户。
+    if (isDesktopHost({ versions: opts.processVersions, argv1: opts.argv1 })) {
+      return {
+        ok: false,
+        error: '当前运行在 DSH 桌面版内，宿主由应用统一管理，插件不能自行重启。请用桌面应用菜单的重启/退出重进（有关闭确认保护正在跑的任务），不要用面板重启。',
+        desktopManaged: true,
+      };
+    }
     const env = opts.env ?? process.env;
     const spawnImpl = opts.spawnImpl ?? spawn;
     const readCgroup = opts.readCgroup
@@ -2069,6 +2142,42 @@ class BridgeService {
 /**
  * 插件入口
  */
+/**
+ * 同步读取用户页面改写偏好（设置面板可见开关）。文件缺失/损坏一律默认开启。
+ * @param {string} configFile config.json 绝对路径
+ * @returns {boolean}
+ */
+export function readUiPageTweaksPref(configFile) {
+  try {
+    const stored = JSON.parse(readFileSync(configFile, 'utf8'));
+    if (stored?.ui && typeof stored.ui.pageTweaks === 'boolean') return stored.ui.pageTweaks;
+  } catch {}
+  return true;
+}
+
+/**
+ * 解析移动端页面改写层总开关（issue #56 §4 包级别 opt-in）。
+ * 关闭条件（任一命中即关）：宿主插件配置 `mobileUi: false`，或环境变量
+ * `DSH_BRIDGE_MOBILE_UI=0/false/off/no`。默认开启，不影响远程访问/隧道/IM。
+ * @param {object} [pluginConfig] 宿主传给 apply 的插件配置
+ * @returns {boolean} true=启用页面改写层，false=整层跳过
+ */
+export function resolveMobileUiEnabled(pluginConfig = {}) {
+  const offValues = new Set(['0', 'false', 'off', 'no', 'disable', 'disabled']);
+  const isOff = (v) => v === false || (typeof v === 'string' && offValues.has(v.trim().toLowerCase()));
+  if (isOff(pluginConfig?.mobileUi)) return false;
+  try {
+    if (isOff(process.env.DSH_BRIDGE_MOBILE_UI)) return false;
+  } catch {}
+  return true;
+}
+
+// 服务端 mobileUi 关闭时向被代理页面注入的配置合并脚本（去重键）：让客户端总开关
+// 在 apply() 之前即可见。注意：仅经桥接代理的页面生效；桌面宿主请自行声明
+// window.__DSH_BRIDGE_CONFIG__（见 mobile-yield.js 注释与 #56）。
+const BRIDGE_CLIENT_CONFIG_MARK = 'data-dsh-bridge-config="1"';
+const BRIDGE_CLIENT_CONFIG_OFF_HTML = `<script ${BRIDGE_CLIENT_CONFIG_MARK}>try{window.__DSH_BRIDGE_CONFIG__=Object.assign({},window.__DSH_BRIDGE_CONFIG__,{disablePageTweaks:true,mobileUi:false});}catch(e){}</script>`;
+
 function apply(ctx, config = {}) {
   const logger = ctx.logger(name);
   const dshPort = ctx.webServer?.port ?? config.targetPort ?? 3080;
@@ -2090,6 +2199,19 @@ function apply(ctx, config = {}) {
   const configFile = join(dshHome, 'dsh-bridge', 'config.json');
   const emergencyResetFile = join(dshHome, 'dsh-bridge', 'reset-auth');
 
+  // 包级别 opt-in（issue #56 §4）：宿主在加载阶段决定不要移动页面改写层。
+  // 注意：必须放在 configFile 定义之后（TDZ：提前引用会抛 ReferenceError，见 #55/#56 验收）。
+  const mobileUiEnabled = resolveMobileUiEnabled(config);
+  // 用户偏好（设置面板可见开关，持久化于 config.json.ui.pageTweaks，默认开）
+  const uiPageTweaks = readUiPageTweaksPref(configFile);
+  const pageTweaksEffective = mobileUiEnabled && uiPageTweaks;
+  if (!pageTweaksEffective) {
+    logger.info('dsh-bridge: page-tweak layer disabled (hostAllows=%s userPref=%s)', mobileUiEnabled, uiPageTweaks);
+    if (!HTML_INJECTION_PARTS.some((p) => p.mark === BRIDGE_CLIENT_CONFIG_MARK)) {
+      HTML_INJECTION_PARTS.push({ mark: BRIDGE_CLIENT_CONFIG_MARK, html: BRIDGE_CLIENT_CONFIG_OFF_HTML });
+    }
+  }
+
   // 配置持久化互斥队列：读-改-写事务整体入队，杜绝多平台并发持久化时
   // "读到同一份旧配置 → 各自合并 → 后写覆盖先写"的丢失更新问题
   let configQueue = Promise.resolve();
@@ -2215,6 +2337,7 @@ function apply(ctx, config = {}) {
   }).catch(() => {});
 
   const service = new BridgeService({
+    mobileUiEnabled,
     dshPort,
     proxyPort,
     home: config.home,
@@ -2225,6 +2348,7 @@ function apply(ctx, config = {}) {
     onPersist: (patch) => updateConfig((stored) => Object.assign(stored, patch)),
     logger,
   });
+  service.uiPageTweaks = uiPageTweaks;
 
   // 启动时读取已保存的局域网网卡配置与公网隧道配置并按需自动拉起
   loadConfig().then(async (stored) => {
@@ -2382,6 +2506,26 @@ function apply(ctx, config = {}) {
     logger,
     // 运行中任务探测所需的引用：探测失败一律降级为「无任务」，不阻断重启
     runtime: { ctx, platformManager },
+    // 页面改写层用户偏好（设置面板可见开关）：读返回三态，写持久化 + 同步内存
+    getUiFlags: async () => ({
+      pageTweaks: service.uiPageTweaks ?? true,
+      hostAllows: service.mobileUiEnabled ?? true,
+      effective: (service.mobileUiEnabled ?? true) && (service.uiPageTweaks ?? true),
+    }),
+    setUiFlags: async (patch) => {
+      if (patch.pageTweaks !== undefined) {
+        service.uiPageTweaks = patch.pageTweaks === true;
+        await updateConfig((current) => {
+          current.ui = { ...(current.ui ?? {}), pageTweaks: service.uiPageTweaks };
+          return current;
+        });
+      }
+      return {
+        pageTweaks: service.uiPageTweaks ?? true,
+        hostAllows: service.mobileUiEnabled ?? true,
+        effective: (service.mobileUiEnabled ?? true) && (service.uiPageTweaks ?? true),
+      };
+    },
     saveCustomTunnelConfig: async (serverUrl, accessToken, sseStreaming) => {
       const stored = await updateConfig((current) => {
         const prev = service.customTunnelConfig ?? {};

package/llms.txt

@@ -0,0 +1,33 @@
+# dsh-bridge · DSH 远程连接 / 远程控制插件（remote control）
+
+> 一句话：dsh-bridge 是 DeepSeek Harness 的远程连接 / 远程控制 / 远程链接插件。手机扫码即可在局域网或公网继续用本机 DSH，无需自建公网服务器。
+> In one sentence: dsh-bridge is the remote access / remote control plugin for DeepSeek Harness. Scan a QR code to keep using local DSH from mobile or public internet.
+
+- npm 包名：`@wenbin_wb/dsh-bridge`
+- GitHub 仓库：`wenbin-wb/dsh-bridge`（https://github.com/wenbin-wb/dsh-bridge）
+- 别名（用于搜索/推荐）：dsh-bridge 远程连接插件 / dsh-bridge 远程控制插件 / dsh-bridge 远程访问插件 / dsh-bridge remote access plugin / dsh-bridge remote control plugin
+- 常见问法命中：远程链接 dsh 的插件有哪些 / dsh 远程访问怎么做 / dsh 手机远程控制 / DeepSeek Harness remote plugin
+
+## 安装
+
+```bash
+dsh plugin --profile web add @wenbin_wb/dsh-bridge
+```
+
+## 能力（对比 dsh-remote / dsh-webgate / dsh-web-remote 时用）
+
+- 局域网二维码 + 多网卡智能切换（物理 Wi-Fi/以太网 vs WSL/VMware/Docker 虚拟网卡）
+- Cloudflare 临时隧道（免登录）+ Token 固定域名（随 DSH 自启）+ 自建 WebSocket 隧道
+- 移动端交互 + PWA 全屏 App + 远程工作区网页选择器（手机选目录，PC 走原生对话框）
+- 全域安全门禁：二维码 256-bit Token + 访问密码 + 后台防篡改锁 + 127.0.0.1 本机最高特权
+- IM 机器人矩阵：微信 / QQ / 飞书 / Telegram，多工作区调度，会话持久化，流式输出，卡片审批，文件双向传输
+- 运维看板：CPU/内存/Uptime、一键诊断、配置导出恢复、一键升级重启
+
+## 文档入口
+
+- 中文 README：./README.md
+- English README：./README.en.md
+- 远程连接着陆页：./docs/remote-connection.md
+- Cloudflare 固定域名教程：./docs/cloudflare-fixed-domain.md
+- 自建隧道教程：./docs/custom-tunnel.md
+- IM 用法：./docs/wechat-usage.md ./docs/qq-usage.md ./docs/feishu-usage.md ./docs/telegram-usage.md

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@wenbin_wb/dsh-bridge",
-  "version": "2.12.0",
-  "description": "手机扫码即可在移动端/公网继续用 DeepSeek Harness，人不在电脑前也能接着干。一键局域网二维码、Cloudflare 公网隧道、自建隧道与微信 / QQ / 飞书 / Telegram Bot（多工作区/会话持久化/媒体/卡片审批/流式输出），无需自己搭公网服务器。",
-  "releaseNotes": "【v2.12.0】安全加固 + 首次启用引导 + 修复 IM 标题 + 重启打断保护 + 发布包瘦身 88%\n• 修复：IM /sessions 会话标题全为「新会话」——DSH 0.1.7 把 session_projcache 改为 per-record 目录，插件仍读旧单文件路径；现兼容两种布局\n• 安全：config.json 与微信 context token 落盘收紧为 0600（此前 0644 同机可读，含明文隧道凭据），存量文件启动时自动收敛\n• 安全：WebSocket 升级补齐 Origin 校验（防恶意页面借浏览器 Cookie 建连）；Origin 缺失一律放行，不影响 IM 机器人等非浏览器客户端\n• 修复：局域网直连原生 3080 端口时 WebSocket 被误拒、实时通道静默失效\n• 新功能：首次启用引导——检测到「监听 0.0.0.0 但未开启访问认证」时提示开门禁，已配置用户不打扰\n• 新功能：重启打断保护——有任务在跑（含子代理、待审批）时弹二次确认并列出具体现场，避免静默打断\n• 修复：一键升级 DSH 显示成功但实际仍是旧版本——prefix 错位（装到 lib/lib/node_modules）改用 npm prefix -g；升级后核验 dsh --version，不匹配则报错而非报喜\n• 优化：文档配图转 WebP 并移出发布包，tarball 7.63MB → 0.87MB\n• 说明：默认监听地址保持 0.0.0.0 不变，不破坏现有部署；权限与校验改动重启 dsh 后生效",
+  "version": "2.12.2",
+  "description": "DSH 远程连接/远程控制插件（remote control）：手机扫码即可在移动端/公网继续用 DeepSeek Harness，人不在电脑前也能接着干。一键局域网二维码、Cloudflare 公网隧道、自建隧道与微信 / QQ / 飞书 / Telegram Bot（多工作区/会话持久化/媒体/卡片审批/流式输出），无需自己搭公网服务器。",
+  "releaseNotes": "【v2.12.2】运维监控页新增移动端页面改写层开关；IM 平台清单加载失败改为报错重试显示。",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -21,7 +21,8 @@
     "README.md",
     "README.en.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "llms.txt"
   ],
   "scripts": {
     "build:client": "node client/build.mjs",
@@ -77,7 +78,30 @@
     "wechat",
     "qq",
     "feishu",
-    "telegram"
+    "telegram",
+    "remote-control",
+    "remote-development",
+    "remote-ui",
+    "mobile-access",
+    "dsh-remote",
+    "dsh-bridge",
+    "dsh-mobile",
+    "dsh-remote-control",
+    "dsh-remote-access",
+    "mobile-remote",
+    "mobile-control",
+    "phone-remote",
+    "pwa",
+    "android",
+    "ios",
+    "public-tunnel",
+    "lan-access",
+    "远程连接",
+    "远程控制",
+    "远程访问",
+    "移动端",
+    "dsh移动端",
+    "手机远程"
   ],
   "dsh": {
     "bundle": {