@wenbin_wb/dsh-bridge 2.10.15 → 2.11.1

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();
+  });
+}

package/client/settings-nav-icon.js

@@ -0,0 +1,90 @@
+// dsh-bridge 设置页左侧导航栏图标定制 (替换默认小齿轮)
+//
+// 背景：
+// DSH 0.1.x 的设置弹窗外壳（@deepseek-ai/dsh-client-ui-settings-general）仅内置了原生
+// 三个 section 的图标（models, agent-presets, plugins），对第三方插件注册的 settings.section，
+// 外壳一律 fallback 显示其默认的小齿轮图标（gear）。
+//
+// 解决方案（对齐 dshmarket 与 dsh-better-sidebar）：
+// 监听设置弹窗挂载，定位到文本匹配「远程访问」的 nav 按钮，通过 CSS mask 将原生齿轮
+// 替换为专属的「手机 + 远程无线连接」矢量图标，颜色跟随 currentColor 保持原生悬停与激活态一致。
+
+export const SETTINGS_NAV_MARKER = 'data-dsh-bridge-settings-nav';
+
+/**
+ * 远程访问专属图标：手机 + 无线连接电波 (24x24 viewBox)
+ */
+export const 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>`;
+
+/**
+ * 生成导航栏图标样式
+ * @param {string} [customSvg] 可选自定义 SVG 字符串
+ * @returns {string}
+ */
+export 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;
+}
+`;
+}
+
+/**
+ * 注册设置页导航图标适配器
+ *
+ * @param {() => string} [resolveLabel] 获取当前标签文本的回调
+ * @returns {() => void} 清理函数
+ */
+export function registerSettingsNavIcon(resolveLabel = () => '远程访问') {
+  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() : '远程访问';
+    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();
+  };
+}

package/docs/release-process.md

@@ -20,7 +20,12 @@
 
 1. **改版本**：`package.json` 的 `version` + `releaseNotes`
 2. **写 CHANGELOG**：`CHANGELOG.md` 顶部新增对应版本条目
-3. **构建与测试**：`npm run build:lark` + `npm run build:client` + `npm run build:banner` + `npm test`（全量 166 项）
+3. **构建与测试**：
+   - `npm run build:client`（**必须**：客户端产物要与源码同步，`npm test` 有一项断言会校验产物内嵌的 CSS 与源码逐字一致）
+   - `npm test` + `npm run lint`
+   - `npm run verify:mobile-ui`（**发布前必做**：跑真实 GUI 的移动端行为验收，6 个套件。需要 dsh web 正在运行；Chrome 路径可用 `PUPPETEER_EXECUTABLE_PATH` 指定。它不在 CI 里跑，因为 CI 没有宿主）
+   - `npm run build:banner`（**仅当 `docs/screenshots/` 素材有变、需要重出 README banner 时执行**；输入没变时应跳过，否则只会产生 JPEG 重编码噪声。注意该脚本默认 Chrome 路径是写死的 Windows 路径，需用 `PUPPETEER_EXECUTABLE_PATH` 覆盖）
+   - `npm run build:lark`（**仅在需要重建飞书 vendor bundle 时执行**。它用当前 esbuild 重新打包 `lib/feishu/lark-bundled.mjs`，产物会随 esbuild 版本漂移；**不要放进 `prepack`**，否则每次 `npm publish` 都会让线上 tarball 里的 vendor 文件与 tag 里的不一致）
 4. **提交**：合并到 `main`（fast-forward），提交信息 `release: vX.Y.Z — ...`
 5. **打 tag**：`git tag vX.Y.Z && git push origin vX.Y.Z`（触发 GitHub Actions 自动创建 Release）
 6. **npm 发布**：`npm publish`（prepack 自动构建产物）