@wenbin_wb/dsh-bridge 2.10.15 → 2.11.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@
 
 ---
 
+## [v2.11.0] - 2026-09-28
+
+> 本版为客户端架构升级与环境解耦：支持桌面端宿主（如 Tauri）将设置面板作为独立组件嵌入并动态管理设置页入口；同时为 Android 移动壳及第三方自适应插件引入环境自适应让位与多级特性开关，消除界面冲突与遮挡。
+
+### ✨ 新功能
+
+- **客户端宿主接入面（对齐 #51）**：在客户端入口暴露 Cordis 反射服务 `ctx.provide('dsh-bridge', { version: 1, render, setSettingsVisible, settingsVisible, configureFeatures, getFeatures })`。桌面端宿主（如 DSH Desktop / Tauri）可调用 `render()` 将 `BridgePanel` 现构造嵌入自定义侧栏或扩展容器，支持 `preferredTab` 指定默认停靠页并保持动态响应；收编后可调用 `setSettingsVisible(false)` 动态撤下全局设置页中的重复条目。老宿主环境下平稳降级。
+- **设置页左侧导航栏图标定制**：新增 `client/settings-nav-icon.js`，通过 CSS mask 将设置中心原生回退的通用小齿轮（gear）替换为「远程访问 / 手机无线连接」专属矢量图标，颜色自动跟随 `currentColor` 保持原生悬停与激活态一致。
+- **移动端多级特性开关与排障支持（对齐 #52）**：新增 `client/mobile-yield.js`，支持通过 URL 查询参数（如 `?dsh_bridge_tweaks=0` 全局禁用、`?dsh_mobile_header=0` 仅禁用顶栏）、宿主全局配置（`window.__DSH_BRIDGE_CONFIG__`）、运行时反射服务或本地存储细粒度控制移动端 UI 特性。
+
+### 🐞 修复
+
+- **Android 移动壳/已有自适应插件下的界面冲突与顶栏遮挡（#52）**：在 Android 原生 WebView 壳（如 `com.dsharnessmobile.shell`）或已加载移动自适应插件（如 `@dsh-android/dsh-client-ui-responsive`）的环境下，插件主动避让自建 body 级顶栏与全局覆盖样式，杜绝双重顶栏重叠、设置页错位与触控遮挡失效。
+
+### 🧪 测试
+
+- 新增 `test/mobile-yield.test.mjs`（11 条）、`test/client-provide.test.mjs`（6 条）与 `test/settings-nav-icon.test.mjs`（3 条），全量 337 项测试 100% 通过。
+
+> ⚠️ 生效说明：纯前端改动，刷新页面即可生效，无需重启 dsh。
+
+---
+
 ## [v2.10.15] - 2026-09-25
 
 > 本版为设置页关闭按钮的可用性微调：手机上「✕」更容易点中。

package/client/client.js

@@ -1374,6 +1374,166 @@ function shouldYieldToOfficialPicker(facts) {
   return Boolean(facts?.local) && Boolean(facts?.officialPicker);
 }
 
+// client/mobile-yield.js
+var FEATURES = {
+  MOBILE_HEADER: "mobileHeader",
+  MOBILE_STYLES: "mobileStyles",
+  COMPOSER_COLLAPSE: "composerCollapse"
+};
+var runtimeFeatureOverrides = {};
+function setRuntimeFeatureOverrides(overrides) {
+  if (overrides && typeof overrides === "object") {
+    runtimeFeatureOverrides = { ...runtimeFeatureOverrides, ...overrides };
+  }
+}
+function getRuntimeFeatureOverrides() {
+  return { ...runtimeFeatureOverrides };
+}
+function detectMobileShellOrResponsivePlugin() {
+  if (typeof window === "undefined") return false;
+  if (window.__DSH_MOBILE_SHELL__ || window.__TAURI__ || window.__DSH_DESKTOP__) {
+    return true;
+  }
+  if (window.__DSH_CLIENT_UI_RESPONSIVE__) {
+    return true;
+  }
+  if (typeof document !== "undefined") {
+    if (document.querySelector("[data-dsh-responsive-mobile]") || document.querySelector("[data-dsh-mobile-shell]")) {
+      return true;
+    }
+  }
+  return false;
+}
+function isFeatureEnabled(featureName, defaultDetector) {
+  if (typeof window === "undefined") {
+    return typeof defaultDetector === "function" ? defaultDetector() : true;
+  }
+  try {
+    if (window.location && window.location.search) {
+      const params = new URLSearchParams(window.location.search);
+      const tweaksVal = params.get("dsh_bridge_tweaks") ?? params.get("dsh_mobile_tweaks");
+      if (tweaksVal === "0" || tweaksVal === "false" || tweaksVal === "off") {
+        return false;
+      }
+      if (tweaksVal === "1" || tweaksVal === "true" || tweaksVal === "on") {
+        return true;
+      }
+      const kebabName = featureName.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`);
+      const specificVal = params.get(`dsh_${kebabName}`) ?? params.get(`dsh_${featureName}`);
+      if (specificVal === "0" || specificVal === "false" || specificVal === "off") {
+        return false;
+      }
+      if (specificVal === "1" || specificVal === "true" || specificVal === "on") {
+        return true;
+      }
+    }
+  } catch {
+  }
+  try {
+    const hostConfig = window.__DSH_BRIDGE_CONFIG__;
+    if (hostConfig && typeof hostConfig === "object") {
+      if (hostConfig.disablePageTweaks === true || hostConfig.disableMobileTweaks === true) {
+        return false;
+      }
+      if (typeof hostConfig[featureName] === "boolean") {
+        return hostConfig[featureName];
+      }
+    }
+  } catch {
+  }
+  if (typeof runtimeFeatureOverrides[featureName] === "boolean") {
+    return runtimeFeatureOverrides[featureName];
+  }
+  try {
+    if (window.localStorage) {
+      const stored = window.localStorage.getItem(`dsh_bridge:feature:${featureName}`);
+      if (stored === "0" || stored === "false") return false;
+      if (stored === "1" || stored === "true") return true;
+    }
+  } catch {
+  }
+  if (typeof defaultDetector === "function") {
+    return defaultDetector();
+  }
+  return true;
+}
+function shouldYieldMobileHeader() {
+  return !isFeatureEnabled(FEATURES.MOBILE_HEADER, () => {
+    return !detectMobileShellOrResponsivePlugin();
+  });
+}
+function shouldYieldMobileStyles() {
+  return !isFeatureEnabled(FEATURES.MOBILE_STYLES, () => {
+    return !detectMobileShellOrResponsivePlugin();
+  });
+}
+function shouldYieldComposerCollapse() {
+  return !isFeatureEnabled(FEATURES.COMPOSER_COLLAPSE, () => {
+    return !detectMobileShellOrResponsivePlugin();
+  });
+}
+
+// client/settings-nav-icon.js
+var SETTINGS_NAV_MARKER = "data-dsh-bridge-settings-nav";
+var REMOTE_NAV_SVG = `<svg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><rect width='10' height='16' x='3' y='4' rx='2'/><path d='M7 16h2'/><path d='M17 8a4 4 0 0 1 0 8'/><path d='M20 5a8 8 0 0 1 0 14'/></svg>`;
+function getNavIconCss(customSvg = REMOTE_NAV_SVG) {
+  const maskUrl = `data:image/svg+xml,${encodeURIComponent(customSvg)}`;
+  return `
+[${SETTINGS_NAV_MARKER}] > svg:first-child {
+  display: none !important;
+}
+[${SETTINGS_NAV_MARKER}]::before {
+  content: '';
+  flex: none;
+  width: 16px;
+  height: 16px;
+  background-color: currentColor;
+  -webkit-mask: url("${maskUrl}") center / contain no-repeat;
+  mask: url("${maskUrl}") center / contain no-repeat;
+}
+`;
+}
+function registerSettingsNavIcon(resolveLabel = () => "\u8FDC\u7A0B\u8BBF\u95EE") {
+  if (typeof document === "undefined") return () => {
+  };
+  const styleId = "dsh-bridge-settings-nav-icon-style";
+  if (!document.getElementById(styleId)) {
+    const style = document.createElement("style");
+    style.id = styleId;
+    style.dataset.plugin = "@wenbin_wb/dsh-bridge";
+    style.dataset.pluginCss = "@wenbin_wb/dsh-bridge/settings-nav-icon";
+    style.textContent = getNavIconCss();
+    document.head.appendChild(style);
+  }
+  let disposed = false;
+  const sync = () => {
+    if (disposed) return;
+    const currentLabel = typeof resolveLabel === "function" ? resolveLabel().trim() : "\u8FDC\u7A0B\u8BBF\u95EE";
+    const buttons = document.querySelectorAll('[role="dialog"] nav button, div[class*="VOzbGW_nav"] button');
+    for (const button of buttons) {
+      const text = button.textContent?.trim() || "";
+      if (currentLabel.length > 0 && (text === currentLabel || text.includes(currentLabel))) {
+        button.setAttribute(SETTINGS_NAV_MARKER, "");
+      } else if (button.hasAttribute(SETTINGS_NAV_MARKER)) {
+        button.removeAttribute(SETTINGS_NAV_MARKER);
+      }
+    }
+  };
+  sync();
+  let observer = null;
+  if (typeof MutationObserver !== "undefined") {
+    observer = new MutationObserver(sync);
+    observer.observe(document.body, { childList: true, subtree: true, characterData: true });
+  }
+  return () => {
+    disposed = true;
+    if (observer) observer.disconnect();
+    document.querySelectorAll(`[${SETTINGS_NAV_MARKER}]`).forEach((el) => el.removeAttribute(SETTINGS_NAV_MARKER));
+    const styleEl = document.getElementById(styleId);
+    if (styleEl) styleEl.remove();
+  };
+}
+
 // lib/bridge-rpc-constants.js
 var BRIDGE_RPC_CHANNEL = "/dsh-bridge";
 var BRIDGE_ENDPOINTS = {
@@ -4860,10 +5020,13 @@ function TabBar({ active, onChange, dots }) {
     })
   );
 }
-function BridgePanel({ rpcCall }) {
+function BridgePanel({ rpcCall, preferredTab }) {
   const [status, setStatus] = React.useState(null);
   const [err, setErr] = React.useState(null);
-  const [activeTab, setActiveTab] = React.useState("lan");
+  const [activeTab, setActiveTab] = React.useState(preferredTab || "lan");
+  React.useEffect(() => {
+    if (preferredTab) setActiveTab(preferredTab);
+  }, [preferredTab]);
   const [platforms, setPlatforms] = React.useState(null);
   const [selectedPlatform, setSelectedPlatform] = React.useState("wechat");
   const [copiedUrl, setCopiedUrl] = React.useState("");
@@ -5645,6 +5808,7 @@ function BridgePanel({ rpcCall }) {
 }
 function injectMobileStyles() {
   if (typeof document === "undefined") return;
+  if (shouldYieldMobileStyles()) return;
   if (document.getElementById("dsh-bridge-mobile-styles")) return;
   const style = document.createElement("style");
   style.id = "dsh-bridge-mobile-styles";
@@ -5703,6 +5867,7 @@ function setupSettingsDrilldown() {
 function setupMobileExperience(rpcCall, ctx) {
   if (typeof document === "undefined" || typeof window === "undefined") return;
   injectMobileStyles();
+  if (shouldYieldMobileHeader()) return;
   let header = document.querySelector(".dsh-mobile-app-header");
   let titleEl = document.querySelector(".dsh-mobile-header-title");
   if (!header) {
@@ -6659,8 +6824,9 @@ function setupIosKeyboardAdapter() {
   });
 }
 function setupComposerCollapse() {
-  if (typeof window === "undefined" || typeof document === "undefined") return;
+  if (typeof window === "undefined" || typeof document === "undefined" || typeof MutationObserver === "undefined") return;
   if (window.innerWidth > MOBILE_MAX_WIDTH) return;
+  if (shouldYieldComposerCollapse()) return;
   const LS_KEY = "dsh-composer-fold";
   let bar = null;
   let busy = false;
@@ -6793,6 +6959,11 @@ function setupComposerCollapse() {
 function apply(ctx) {
   window.__dshClientCtx = ctx;
   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 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();
@@ -6824,19 +6995,74 @@ function apply(ctx) {
       );
     })
   );
-  ctx.slots.inject(
-    "settings.section",
-    () => ctx.slots.register(
-      {
-        name: "settings.section",
-        id: "dsh-bridge",
-        order: 10,
-        label: () => "\u8FDC\u7A0B\u8BBF\u95EE",
-        inject: () => ({ rpcCall })
-      },
-      BridgePanel
-    )
-  );
+  let settingsVisible = true;
+  let sectionRegistration = null;
+  const ensureSectionRegistered = () => {
+    if (!settingsVisible || sectionRegistration) return;
+    try {
+      sectionRegistration = ctx.slots.register(
+        {
+          name: "settings.section",
+          id: "dsh-bridge",
+          order: 10,
+          label: () => "\u8FDC\u7A0B\u8BBF\u95EE",
+          inject: () => ({ rpcCall })
+        },
+        BridgePanel
+      );
+    } catch {
+    }
+  };
+  const ensureSectionUnregistered = () => {
+    if (!sectionRegistration) return;
+    try {
+      if (typeof sectionRegistration === "function") {
+        sectionRegistration();
+      } else if (typeof sectionRegistration.dispose === "function") {
+        sectionRegistration.dispose();
+      }
+    } catch {
+    }
+    sectionRegistration = null;
+  };
+  const sectionGate = {
+    visible: () => settingsVisible,
+    setVisible: (visible) => {
+      const next = !!visible;
+      if (settingsVisible === next) return;
+      settingsVisible = next;
+      if (next) {
+        ensureSectionRegistered();
+      } else {
+        ensureSectionUnregistered();
+      }
+    }
+  };
+  ctx.slots.inject("settings.section", () => {
+    if (settingsVisible) {
+      ensureSectionRegistered();
+    }
+  });
+  const bridgeControl = {
+    version: 1,
+    /** 把插件自己的面板交给宿主渲染（返回 React element） */
+    render: (props = {}) => {
+      return React.createElement(BridgePanel, {
+        rpcCall,
+        preferredTab: props.preferredTab,
+        ...props
+      });
+    },
+    /** 宿主收编面板后，撤下设置页那条重复入口 */
+    setSettingsVisible: (visible) => sectionGate.setVisible(visible),
+    settingsVisible: () => sectionGate.visible(),
+    /** 运行时动态特性开关配置 (Issue #52) */
+    configureFeatures: (flags) => setRuntimeFeatureOverrides(flags),
+    getFeatures: () => getRuntimeFeatureOverrides()
+  };
+  if (typeof ctx.provide === "function") {
+    ctx.provide("dsh-bridge", bridgeControl);
+  }
 }
 
     return module.exports;

package/client/index.js

@@ -5,6 +5,14 @@ import {
   fetchLoopbackTokenOnce,
 } from './unlock-manager.js'
 import { hasOfficialDirectoryPicker, shouldYieldToOfficialPicker } from './picker-yield.js'
+import {
+  shouldYieldMobileHeader,
+  shouldYieldMobileStyles,
+  shouldYieldComposerCollapse,
+  setRuntimeFeatureOverrides,
+  getRuntimeFeatureOverrides,
+} from './mobile-yield.js'
+import { registerSettingsNavIcon } from './settings-nav-icon.js'
 // dsh-bridge 客户端插件：设置页「远程访问」面板
 
 // 兼容非 HTTPS 环境（如手机局域网 HTTP 访问）：为非安全上下文补齐 crypto.randomUUID
@@ -3081,10 +3089,13 @@ function TabBar({ active, onChange, dots }) {
 
 // ---- 主面板 ----
 
-function BridgePanel({ rpcCall }) {
+function BridgePanel({ rpcCall, preferredTab }) {
   const [status, setStatus]       = React.useState(null);
   const [err, setErr]             = React.useState(null);
-  const [activeTab, setActiveTab] = React.useState('lan');
+  const [activeTab, setActiveTab] = React.useState(preferredTab || 'lan');
+  React.useEffect(() => {
+    if (preferredTab) setActiveTab(preferredTab);
+  }, [preferredTab]);
   // 平台列表和连接状态
   const [platforms, setPlatforms] = React.useState(null);
   const [selectedPlatform, setSelectedPlatform] = React.useState('wechat');
@@ -3819,6 +3830,7 @@ function BridgePanel({ rpcCall }) {
 
 function injectMobileStyles() {
   if (typeof document === 'undefined') return;
+  if (shouldYieldMobileStyles()) return;
   if (document.getElementById('dsh-bridge-mobile-styles')) return;
 
   const style = document.createElement('style');
@@ -3915,6 +3927,7 @@ function setupSettingsDrilldown() {
 function setupMobileExperience(rpcCall, ctx) {
   if (typeof document === 'undefined' || typeof window === 'undefined') return;
   injectMobileStyles();
+  if (shouldYieldMobileHeader()) return;
 
   // 1. 创建顶部 DeepSeek App 风格导航条 (Header: 左侧双横线，中间当前会话标题，右侧(+))
   let header = document.querySelector('.dsh-mobile-app-header');
@@ -5067,8 +5080,9 @@ function setupIosKeyboardAdapter() {
 // 中间消息可视区很小。折叠后 composer 隐藏、消息 viewArea 自动伸展全高，阅读区显著增大。
 // 折叠态记忆到 localStorage（dsh-composer-fold），跨会话保持用户偏好。
 function setupComposerCollapse() {
-  if (typeof window === 'undefined' || typeof document === 'undefined') return;
+  if (typeof window === 'undefined' || typeof document === 'undefined' || typeof MutationObserver === 'undefined') return;
   if (window.innerWidth > MOBILE_MAX_WIDTH) return; // 仅移动端
+  if (shouldYieldComposerCollapse()) return;
   const LS_KEY = 'dsh-composer-fold';
 
   let bar = null;          // 折叠态底部"点击输入"细条
@@ -5197,6 +5211,12 @@ function apply(ctx) {
   // 放在最前：交互层先就绪，后续任何初始化抛异常都不会留下「CSS 生效但监听器缺失」
   // 的状态（CSS 6.2 块另有 <html> 就绪开关双重兜底）。
   setupSettingsDrilldown();
+  // 设置页左侧导航栏图标定制：将原生通用齿轮替换为远程访问专属图标
+  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);
 
@@ -5245,18 +5265,80 @@ function apply(ctx) {
     }),
   );
 
-  ctx.slots.inject('settings.section', () =>
-    ctx.slots.register(
-      {
-        name: 'settings.section',
-        id: 'dsh-bridge',
-        order: 10,
-        label: () => '远程访问',
-        inject: () => ({ rpcCall }),
-      },
-      BridgePanel,
-    ),
-  );
+  // 设置页条目动态门控与可见性管理 (Issue #51)
+  let settingsVisible = true;
+  let sectionRegistration = null;
+
+  const ensureSectionRegistered = () => {
+    if (!settingsVisible || sectionRegistration) return;
+    try {
+      sectionRegistration = ctx.slots.register(
+        {
+          name: 'settings.section',
+          id: 'dsh-bridge',
+          order: 10,
+          label: () => '远程访问',
+          inject: () => ({ rpcCall }),
+        },
+        BridgePanel,
+      );
+    } catch {}
+  };
+
+  const ensureSectionUnregistered = () => {
+    if (!sectionRegistration) return;
+    try {
+      if (typeof sectionRegistration === 'function') {
+        sectionRegistration();
+      } else if (typeof sectionRegistration.dispose === 'function') {
+        sectionRegistration.dispose();
+      }
+    } catch {}
+    sectionRegistration = null;
+  };
+
+  const sectionGate = {
+    visible: () => settingsVisible,
+    setVisible: (visible) => {
+      const next = !!visible;
+      if (settingsVisible === next) return;
+      settingsVisible = next;
+      if (next) {
+        ensureSectionRegistered();
+      } else {
+        ensureSectionUnregistered();
+      }
+    },
+  };
+
+  ctx.slots.inject('settings.section', () => {
+    if (settingsVisible) {
+      ensureSectionRegistered();
+    }
+  });
+
+  // 暴露客户端反射控制面 (Issue #51)
+  const bridgeControl = {
+    version: 1,
+    /** 把插件自己的面板交给宿主渲染（返回 React element） */
+    render: (props = {}) => {
+      return React.createElement(BridgePanel, {
+        rpcCall,
+        preferredTab: props.preferredTab,
+        ...props,
+      });
+    },
+    /** 宿主收编面板后，撤下设置页那条重复入口 */
+    setSettingsVisible: (visible) => sectionGate.setVisible(visible),
+    settingsVisible: () => sectionGate.visible(),
+    /** 运行时动态特性开关配置 (Issue #52) */
+    configureFeatures: (flags) => setRuntimeFeatureOverrides(flags),
+    getFeatures: () => getRuntimeFeatureOverrides(),
+  };
+
+  if (typeof ctx.provide === 'function') {
+    ctx.provide('dsh-bridge', bridgeControl);
+  }
 }
 
 export { name, inject, apply };

package/client/mobile-yield.js

@@ -0,0 +1,192 @@
+// dsh-bridge 移动端体验与界面改动层的「让位与开关」机制 (Issue #52)
+//
+// 背景：
+// dsh-bridge 为了在移动端网页访问（纯手机浏览器/局域网扫码）时提供类 App 的移动交互，
+// 自建了 body 级导航条（.dsh-mobile-app-header）、输入框折叠按钮以及一套含 !important
+// 的移动端全局覆盖样式。
+//
+// 但在以下环境，这一层自绘会引发严重冲突：
+// 1. Android 原生 WebView 壳（如 com.dsharnessmobile.shell），壳层自身已有原生导航栏与手势；
+// 2. 页面已安装专门的响应式插件（如 @dsh-android/dsh-client-ui-responsive），争抢同层 DOM；
+// 3. 桌面端宿主（如 Tauri 桌面端 / DSH Desktop），无需任何移动端 DOM 侵入。
+//
+// 本模块提供「多级开关 + 自动特征探测让位」：
+// 优先级：URL 参数 > 宿主全局注入配置 (__DSH_BRIDGE_CONFIG__) > 运行时动态配置 > 本地存储 > 自动探测兜底
+
+/** 特性名称常量 */
+export const FEATURES = {
+  MOBILE_HEADER: 'mobileHeader',
+  MOBILE_STYLES: 'mobileStyles',
+  COMPOSER_COLLAPSE: 'composerCollapse',
+};
+
+// 内存中的动态运行时覆盖配置（可通过 ctx.reflect.get('dsh-bridge').configureFeatures(...) 设置）
+let runtimeFeatureOverrides = {};
+
+/**
+ * 设置运行时特性覆盖（供 Cordis 反射服务调用）
+ * @param {Record<string, boolean>} overrides
+ */
+export function setRuntimeFeatureOverrides(overrides) {
+  if (overrides && typeof overrides === 'object') {
+    runtimeFeatureOverrides = { ...runtimeFeatureOverrides, ...overrides };
+  }
+}
+
+/**
+ * 获取当前运行时特性状态
+ * @returns {Record<string, boolean>}
+ */
+export function getRuntimeFeatureOverrides() {
+  return { ...runtimeFeatureOverrides };
+}
+
+/**
+ * 重置运行时特性覆盖（主要用于测试）
+ */
+export function resetRuntimeFeatureOverrides() {
+  runtimeFeatureOverrides = {};
+}
+
+/**
+ * 探测是否处于已具备自适应/原生移动顶栏的环境中
+ * @returns {boolean}
+ */
+export function detectMobileShellOrResponsivePlugin() {
+  if (typeof window === 'undefined') return false;
+
+  // 1. 移动端原生/混合壳显式标记
+  if (window.__DSH_MOBILE_SHELL__ || window.__TAURI__ || window.__DSH_DESKTOP__) {
+    return true;
+  }
+
+  // 2. 已加载的移动端自适应插件标记
+  if (window.__DSH_CLIENT_UI_RESPONSIVE__) {
+    return true;
+  }
+
+  // 3. DOM 标记探测（如 @dsh-android/dsh-client-ui-responsive 挂载的特征属性）
+  if (typeof document !== 'undefined') {
+    if (document.querySelector('[data-dsh-responsive-mobile]') ||
+        document.querySelector('[data-dsh-mobile-shell]')) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 探测页面是否已有主顶栏（避免 body 级双顶栏叠加）
+ * @returns {boolean}
+ */
+export function detectExistingHeader() {
+  if (typeof document === 'undefined') return false;
+  // 如果页面中已经有 #root 下的 header 或 banner 角色元素
+  return !!document.querySelector('#root header, [role="banner"]:not(.dsh-mobile-app-header)');
+}
+
+/**
+ * 解析特性开关（返回 true 表示启用，false 表示禁用/让位）
+ *
+ * @param {string} featureName 特性名称
+ * @param {() => boolean} defaultDetector 自动探测兜底函数
+ * @returns {boolean}
+ */
+export function isFeatureEnabled(featureName, defaultDetector) {
+  if (typeof window === 'undefined') {
+    return typeof defaultDetector === 'function' ? defaultDetector() : true;
+  }
+
+  // 1. URL 应急排障参数（最高优先级，支持 ?dsh_bridge_tweaks=0 或 ?dsh_mobile=off 批量禁用）
+  try {
+    if (window.location && window.location.search) {
+      const params = new URLSearchParams(window.location.search);
+      // 总开关：禁用所有页面微调
+      const tweaksVal = params.get('dsh_bridge_tweaks') ?? params.get('dsh_mobile_tweaks');
+      if (tweaksVal === '0' || tweaksVal === 'false' || tweaksVal === 'off') {
+        return false;
+      }
+      if (tweaksVal === '1' || tweaksVal === 'true' || tweaksVal === 'on') {
+        return true;
+      }
+
+      // 单项开关：如 ?dsh_mobile_header=0, ?dsh_mobile_styles=0, ?dsh_composer_collapse=0
+      const kebabName = featureName.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`);
+      const specificVal = params.get(`dsh_${kebabName}`) ?? params.get(`dsh_${featureName}`);
+      if (specificVal === '0' || specificVal === 'false' || specificVal === 'off') {
+        return false;
+      }
+      if (specificVal === '1' || specificVal === 'true' || specificVal === 'on') {
+        return true;
+      }
+    }
+  } catch {}
+
+  // 2. 宿主注入的全局配置对象 window.__DSH_BRIDGE_CONFIG__
+  try {
+    const hostConfig = window.__DSH_BRIDGE_CONFIG__;
+    if (hostConfig && typeof hostConfig === 'object') {
+      if (hostConfig.disablePageTweaks === true || hostConfig.disableMobileTweaks === true) {
+        return false;
+      }
+      if (typeof hostConfig[featureName] === 'boolean') {
+        return hostConfig[featureName];
+      }
+    }
+  } catch {}
+
+  // 3. 动态运行时配置（通过反射 API 设置）
+  if (typeof runtimeFeatureOverrides[featureName] === 'boolean') {
+    return runtimeFeatureOverrides[featureName];
+  }
+
+  // 4. 本地持久化偏好 (localStorage)
+  try {
+    if (window.localStorage) {
+      const stored = window.localStorage.getItem(`dsh_bridge:feature:${featureName}`);
+      if (stored === '0' || stored === 'false') return false;
+      if (stored === '1' || stored === 'true') return true;
+    }
+  } catch {}
+
+  // 5. 自动探测兜底
+  if (typeof defaultDetector === 'function') {
+    return defaultDetector();
+  }
+
+  return true;
+}
+
+/**
+ * 是否应该让位自绘顶栏 (返回 true 表示让位/不自建顶栏)
+ * @returns {boolean}
+ */
+export function shouldYieldMobileHeader() {
+  return !isFeatureEnabled(FEATURES.MOBILE_HEADER, () => {
+    // 自动判定：如果是移动端壳层/已有自适应插件/页面已有顶栏，则主动让位
+    return !detectMobileShellOrResponsivePlugin();
+  });
+}
+
+/**
+ * 是否应该让位移动端全局样式 (返回 true 表示让位/不注入样式)
+ * @returns {boolean}
+ */
+export function shouldYieldMobileStyles() {
+  return !isFeatureEnabled(FEATURES.MOBILE_STYLES, () => {
+    // 自动判定：如果已被外部响应式插件完全接管，则让位全局样式
+    return !detectMobileShellOrResponsivePlugin();
+  });
+}
+
+/**
+ * 是否应该让位输入框折叠按钮 (返回 true 表示让位/不挂载折叠按钮)
+ * @returns {boolean}
+ */
+export function shouldYieldComposerCollapse() {
+  return !isFeatureEnabled(FEATURES.COMPOSER_COLLAPSE, () => {
+    // 自动判定：移动端壳层下输入框折叠按钮容易与原生交互冲突，让位
+    return !detectMobileShellOrResponsivePlugin();
+  });
+}