@wenbin_wb/dsh-bridge 2.10.8 → 2.10.9

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ---
 
+## [v2.10.9] - 2026-09-12
+
+### 🐞 修复
+
+- **DSH 0.1.5 系列上 `dsh web` 启动即崩**（issue #38）：DSH 从 `0.1.5-alpha.1` 起，宿主自带的 `dsh-client-connection` 调整了插件级服务声明却遗漏了一处同步修改，导致凡是注册 RPC 通道的插件都会让**整棵插件树加载失败**、`dsh web` 直接退出（报 `cannot get property "webServer" without inject`）。现已插件侧兼容：正常路径完全不变，仅在命中该宿主缺陷时自动补上解析兜底并完成通道注册，上游修复后自动空转、无副作用。DSH `0.1.5-alpha.1` / `alpha.2` / `rc.1` / `rc.2`（含当前最新版）均已实测通过，`0.1.0`~`0.1.4` 行为不变。
+
+### ✨ 优化
+
+- **与 DSH 原生鉴权（`0.1.2` 起内置）确认兼容并加固**：反代转发时自动注入 DSH 要求的回环会话 cookie，手机 / 局域网 / 隧道访问无需处理 DSH 自身的 `?token=` 登录流程；同时修正凭据解析——当 DSH 凭据文件里存在多条密钥记录时，确保取用浏览器会话记录对应的密钥，避免远程访问出现 401。
+
+---
+
 ## [v2.10.8] - 2026-09-08
 
 ### ✨ 新功能

package/README.en.md

@@ -48,6 +48,7 @@
   - [7. 📊 Maintenance Dashboard & Graceful Restart](#7-📊-maintenance-dashboard--graceful-restart)
 - [💬 FAQ](#-faq)
 - [🛠️ Development & Contribution](#️-development--contribution)
+- [⭐ Star History](#-star-history)
 - [📄 License](#-license)
 
 ---
@@ -77,6 +78,20 @@ node -v   # v22.19+ or v24+
 dsh --version
 ```
 
+### DSH version compatibility
+
+This plugin supports **both old and new DSH releases** — there is no need to pick a plugin version to match your harness.
+
+| DSH version | Status |
+| --- | --- |
+| `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) |
+
+> **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.
+>
+> This is **complementary to, not a duplicate of**, this plugin's access-password gate: the built-in auth protects "the DSH process on local loopback", while this plugin's gate protects "remote access arriving over LAN or a public tunnel". The plugin's reverse proxy injects a valid loopback session cookie while forwarding, so phone / tunnel access needs **no** manual handling of DSH's `?token=` — just use it as documented on this page.
+
 ### Installation
 
 ```bash
@@ -405,6 +420,18 @@ dsh plugin --profile web add .
 
 ---
 
+## ⭐ Star History
+
+<a href="https://www.star-history.com/?repos=wenbin-wb%2Fdsh-bridge&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=wenbin-wb/dsh-bridge&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=wenbin-wb/dsh-bridge&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=wenbin-wb/dsh-bridge&type=date&legend=top-left" />
+ </picture>
+</a>
+
+---
+
 ## 📄 License
 
 MIT © [wenbin-wb](https://github.com/wenbin-wb)

package/README.md

@@ -48,6 +48,7 @@
   - [7. 📊 运维监控看板与一键平滑重启](#7-📊-运维监控看板与一键平滑重启)
 - [💬 常见问题 (FAQ)](#-常见问题-faq)
 - [🛠️ 开发与贡献](#️-开发与贡献)
+- [⭐ Star History](#-star-history)
 - [📄 开源协议](#-开源协议)
 
 ---
@@ -79,6 +80,20 @@ node -v   # 应显示 v22.19+ 或 v24+
 dsh --version
 ```
 
+### DSH 版本兼容性
+
+本插件**同时兼容新旧 DSH**，无需按 DSH 版本挑选插件版本：
+
+| DSH 版本 | 状态 |
+| --- | --- |
+| `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 起） |
+
+> **关于 DSH 原生鉴权**：DSH 从 `0.1.2` 起为 `dsh web` 内置了浏览器鉴权——启动时会打印带一次性 token 的地址（`http://127.0.0.1:3080/?token=…`），换取一枚绑定回环地址的会话 cookie，此后 `/`、`/api` 及各插件 RPC 通道都要求该 cookie。
+>
+> 这与本插件的**访问密码门禁是两层互补的防护**，不冲突也不重复：原生鉴权保护的是"本机回环上的 DSH 进程"，本插件的门禁保护的是"经局域网 / 公网隧道进入的远程访问"。本插件的反向代理会在转发时自动注入合法的回环会话 cookie，因此手机 / 隧道访问**无需**手动处理 DSH 的 `?token=`，按本页说明正常使用即可。
+
 ### 安装插件
 
 ```bash
@@ -427,6 +442,18 @@ dsh plugin --profile web add .
 
 ---
 
+## ⭐ Star History
+
+<a href="https://www.star-history.com/?repos=wenbin-wb%2Fdsh-bridge&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=wenbin-wb/dsh-bridge&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=wenbin-wb/dsh-bridge&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=wenbin-wb/dsh-bridge&type=date&legend=top-left" />
+ </picture>
+</a>
+
+---
+
 ## 📄 开源协议
 
 本项目基于 [MIT 许可证](LICENSE) 开源发布。

package/docs/telegram-usage.md

@@ -90,4 +90,4 @@
 2. **安全白名单拦截**：
    - 仅白名单内的用户消息会被放行给 Agent；非白名单用户发送的消息会被直接忽略，绝不消耗 Token 或喂给模型。
 3. **敏感操作审批**：
-   - 当 Agent 尝试执行系统命令或敏感文件读写时，Telegram 会自动下发 `[✓ 批准执行]` / `[✕ 拒绝执行]` 交互按键，10 分钟未处理自动超时拒绝。
+   - 当 Agent 尝试执行系统命令或敏感文件读写时，Telegram 会自动下发 `[✓ 批准执行]` / `[✕ 拒绝执行]` 交互按键，10 分钟未处理自动超时拒绝。

package/lib/auth/dsh-native-cookie.js

@@ -0,0 +1,148 @@
+// DSH 原生浏览器鉴权的兼容层（lib/auth/dsh-native-cookie.js）
+//
+// 背景
+// ---------------------------------------------------------------
+// DSH 从 0.1.2 起为 `dsh web` 引入了"原生浏览器鉴权"：
+//   1. 启动时打印带一次性 launch token 的地址：http://127.0.0.1:<port>/?token=…
+//   2. `GET /?token=<token>` 校验通过后 303 重定向到 `/`，并下发签名会话 cookie
+//   3. 此后所有受保护路由（`/`、`/api`、以及任何经
+//      `ctx.connection.rpc.handle()` 注册的通道）都要求该 cookie，否则 401
+//
+// cookie 的构造（见 @deepseek-ai/dsh-client-connection 的 BrowserAuth）：
+//   名称：`dsh-auth-` + base64url(sha256(authority))，authority = `127.0.0.1:<port>`
+//   值  ：`v1.<base64url(JSON payload)>.<base64url(HMAC-SHA256(secret, body))>`
+//   载荷：`{ version: 1, authority, issuedAt, expiresAt }`（均为安全整数）
+//   密钥：`<DSH_HOME>/.credentials.yaml` 里 record
+//         `client-connection/browser-session` 的 `payload.secret`（base64url 32 字节）
+//
+// 为什么本插件需要它
+// ---------------------------------------------------------------
+// 本插件的自建反向代理监听自己的端口（默认 3082），对外提供局域网/隧道访问，
+// 再把请求转发到 DSH 回环地址。浏览器持有的是"代理 origin"的 cookie，
+// 而 DSH 的 cookie 绑定的是 `127.0.0.1:<dshPort>` 这个 authority，两者不是同一个，
+// 因此代理必须自行注入一枚合法的 loopback 会话 cookie，否则远程访问会一律 401。
+//
+// 本模块只做"按 DSH 的格式生成一枚回环会话 cookie"，不引入任何三方依赖。
+
+import { createHash, createHmac } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** DSH 会话 cookie 的名称前缀（与 dsh-client-connection 的 COOKIE_PREFIX 一致）。 */
+export const DSH_AUTH_COOKIE_PREFIX = 'dsh-auth-';
+
+/** cookie 载荷版本（与 dsh-client-connection 的 COOKIE_PAYLOAD_VERSION 一致）。 */
+export const DSH_AUTH_COOKIE_VERSION = 1;
+
+/** 会话 cookie 有效期（毫秒）。与 DSH 默认的 cookieMaxAgeDays=30 对齐。 */
+export const DSH_AUTH_COOKIE_MAX_AGE_MS = 30 * 24 * 3600 * 1000;
+
+/** 承载签名密钥的 DSH 凭据记录键。 */
+export const DSH_BROWSER_SESSION_RECORD = 'client-connection/browser-session';
+
+function base64Url(value) {
+  return Buffer.from(value).toString('base64url');
+}
+
+/**
+ * 计算 DSH 会话 cookie 的名称（authority 绑定）。
+ * @param {number|string} targetPort DSH 回环端口
+ * @param {string} [host] 默认 127.0.0.1
+ * @returns {string} 形如 `dsh-auth-<base64url(sha256("127.0.0.1:3080"))>`
+ */
+export function dshAuthCookieName(targetPort, host = '127.0.0.1') {
+  const authority = `${host}:${targetPort}`;
+  return DSH_AUTH_COOKIE_PREFIX + base64Url(createHash('sha256').update(authority).digest());
+}
+
+/**
+ * 从 DSH 凭据文件内容中取出 browser-session 记录的签名密钥。
+ *
+ * 必须精确定位 `client-connection/browser-session` 这条 record：
+ * 凭据文件里还有 `refs:` 段（各家模型 API key）以及可能存在其它插件写入的
+ * record，一旦取到别处的 `secret:`，签名就会无效 —— 现象是"远程访问一律 401"，
+ * 且极难定位。因此先锚定 record 键，再在其后的小范围内取 secret；
+ * 仅当锚点缺失（异常/未来格式）时才退回"全文件第一个 secret:"的旧行为。
+ *
+ * @param {string} content 凭据文件文本
+ * @returns {string} base64url 编码的密钥；取不到时返回空串
+ */
+export function readBrowserSessionSecret(content) {
+  if (typeof content !== 'string' || content === '') return '';
+
+  // 锚定 record 键所在行，随后只在该行往后的一小段内查找 secret
+  const anchorMatch = /^[ \t]*client-connection\/browser-session:[ \t]*$/m.exec(content);
+  if (anchorMatch) {
+    const tail = content.slice(anchorMatch.index);
+    const scoped = /secret:[ \t]*([A-Za-z0-9_-]+)/.exec(tail);
+    if (scoped) return scoped[1];
+  }
+
+  // 兜底：老格式/异常格式下沿用全文件首个 secret:
+  const fallback = /secret:[ \t]*([A-Za-z0-9_-]+)/.exec(content);
+  return fallback ? fallback[1] : '';
+}
+
+/**
+ * 生成一枚绑定到 loopback authority 的 DSH 原生会话 cookie。
+ *
+ * @param {object} opts
+ * @param {number|string} opts.targetPort DSH 回环端口
+ * @param {string} opts.secret base64url 编码的签名密钥
+ * @param {string} [opts.host] 默认 127.0.0.1
+ * @param {number} [opts.now] 当前时间戳（测试注入用）
+ * @param {number} [opts.maxAgeMs] 有效期
+ * @returns {string} `name=value`；密钥缺失时返回空串
+ */
+export function buildDshLoopbackCookie({
+  targetPort,
+  secret,
+  host = '127.0.0.1',
+  now = Date.now(),
+  maxAgeMs = DSH_AUTH_COOKIE_MAX_AGE_MS,
+}) {
+  if (!secret || !targetPort) return '';
+
+  const authority = `${host}:${targetPort}`;
+  const name = dshAuthCookieName(targetPort, host);
+  // 与 DSH 一致：issuedAt 略微回拨，避免与宿主的同秒比较产生边界问题
+  const issuedAt = now - 1000;
+  const expiresAt = issuedAt + maxAgeMs;
+
+  const body = base64Url(Buffer.from(JSON.stringify({
+    version: DSH_AUTH_COOKIE_VERSION,
+    authority,
+    issuedAt,
+    expiresAt,
+  }), 'utf8'));
+  const key = Buffer.from(secret, 'base64url');
+  const sig = base64Url(createHmac('sha256', key).update(body).digest());
+  return `${name}=v${DSH_AUTH_COOKIE_VERSION}.${body}.${sig}`;
+}
+
+/**
+ * 读取本机 DSH 凭据并生成回环会话 cookie（失败时返回空串，绝不抛出）。
+ *
+ * @param {number|string} targetPort DSH 回环端口
+ * @param {object} [env] 便于测试注入的环境
+ * @param {string} [env.dshHome] DSH 主目录（默认 $DSH_HOME 或 ~/.dsh）
+ * @param {Function} [env.readFileSync] 文件读取实现（默认 node:fs）
+ * @param {Function} [env.existsSync] 存在性判断实现
+ * @param {number} [env.now] 当前时间戳
+ * @returns {string} `name=value`，或空串
+ */
+export function getDshLoopbackCookie(targetPort, env = {}) {
+  const readFile = env.readFileSync ?? readFileSync;
+  const exists = env.existsSync ?? existsSync;
+  try {
+    const dshHome = env.dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    const credPath = join(dshHome, '.credentials.yaml');
+    if (!exists(credPath)) return '';
+    const secret = readBrowserSessionSecret(readFile(credPath, 'utf8'));
+    if (!secret) return '';
+    return buildDshLoopbackCookie({ targetPort, secret, now: env.now });
+  } catch {
+    return '';
+  }
+}

package/lib/bridge-rpc.js

@@ -3,6 +3,7 @@
 
 import QRCode from 'qrcode';
 import { BRIDGE_RPC_CHANNEL, BRIDGE_ENDPOINTS } from './bridge-rpc-constants.js';
+import { registerRpcChannel } from './connection-compat.js';
 import { RateLimiter } from './security/rate-limiter.js';
 
 export { BRIDGE_RPC_CHANNEL, BRIDGE_ENDPOINTS };
@@ -87,7 +88,10 @@ export function installBridgeRpc(ctx, { service, authManager, platformManager, l
     return () => {};
   }
 
-  return ctx.connection.rpc.handle(
+  // 经 connection-compat 注册：兼容 DSH ≥ 0.1.5-alpha.1 的 webServer 注入回归
+  // （上游 register() 里对 connection 自身 ctx 取 webServer 而未加 inject 作用域）
+  return registerRpcChannel(
+    ctx,
     BRIDGE_RPC_CHANNEL,
     async (endpoint, payload = {}, signal) => {
       if (signal?.aborted) return fail('cancelled', 'Request was cancelled');
@@ -486,7 +490,10 @@ export function installBridgeRpc(ctx, { service, authManager, platformManager, l
         return fail('bad-request', err.message);
       }
     },
-    { authority: 'loopback' }
+    // DSH 0.1.0/0.1.1 支持 authority 选项（仅回环可达）；0.1.2+ 忽略之，透传无副作用。
+    // 见 lib/connection-compat.js 的 registerRpcChannel 说明。
+    { authority: 'loopback' },
+    logger
   );
 }
 

package/lib/compat.js

@@ -1,129 +1,129 @@
-// 运行时兼容垫片（lib/compat.js）
-//
-// 背景：DSH 核心依赖链（@deepseek-ai/dsh-timeout ← dsh-llm）在每次 agent 请求上
-// 调用 AbortSignal.any([...])，该 API 仅存在于 Node 20.3+/22+。运行在低版本 Node
-// （如 Node 18）上时，通过桥接发送消息会直接抛
-//   "AbortSignal.any is not a function ... (internal)"
-// 本模块在缺失时安装规范兼容的垫片；环境本身支持时不做任何事（返回 false）。
-//
-// 浏览器侧（旧 Safari/WebView）由 lib/index.js 的 HTML_HEAD_INJECTIONS 注入同语义垫片。
-
-function abortWith(controller, reason) {
-  try {
-    controller.abort(reason)
-  } catch {
-    try { controller.abort() } catch { /* 不可中止的信号：忽略 */ }
-  }
-}
-
-/**
- * 在目标环境中安装 AbortSignal.any / AbortSignal.timeout 垫片（仅缺失时）。
- * @param {object} [target] 可注入的环境（默认 globalThis），便于测试
- * @returns {boolean} 是否实际安装了垫片
- */
-export function installAbortSignalCompat(target = globalThis) {
-  const Signal = target.AbortSignal
-  const Controller = target.AbortController
-  if (!Signal || !Controller) return false
-
-  let installed = false
-
-  // ---- AbortSignal.any ----
-  if (typeof Signal.any !== 'function') {
-    Signal.any = (signals) => {
-      const list = Array.from(signals ?? [])
-      const controller = new Controller()
-      // 规范语义：任一源信号已中止 → 立即以该原因中止
-      for (const s of list) {
-        if (s && s.aborted) {
-          abortWith(controller, s.reason)
-          return controller.signal
-        }
-      }
-      const onAbort = (eventOrSignal) => {
-        // 真实 EventTarget 的 abort 事件参数是 event（event.target = 信号），
-        // 部分非标准实现直接传信号本身——两者都兼容取 reason
-        const src = eventOrSignal && eventOrSignal.target ? eventOrSignal.target : eventOrSignal
-        cleanup()
-        abortWith(controller, src ? src.reason : undefined)
-      }
-      const cleanup = () => {
-        for (const s of list) {
-          try { s.removeEventListener('abort', onAbort) } catch { /* 非标准信号：忽略 */ }
-        }
-      }
-      for (const s of list) {
-        try { s.addEventListener('abort', onAbort, { once: true }) } catch { /* 非标准信号：忽略 */ }
-      }
-      return controller.signal
-    }
-    installed = true
-  }
-
-  // ---- AbortSignal.timeout（Node 17.3+ / 较新浏览器才有，顺手补齐）----
-  if (typeof Signal.timeout !== 'function') {
-    Signal.timeout = (delayMs) => {
-      const controller = new Controller()
-      const delay = Math.max(0, Number(delayMs) || 0)
-      const reason = typeof target.DOMException === 'function'
-        ? new target.DOMException('The operation timed out.', 'TimeoutError')
-        : new Error('The operation timed out.')
-      const timer = setTimeout(() => abortWith(controller, reason), delay)
-      // 规范语义：timeout 信号的超时定时器不阻止进程退出
-      if (typeof timer.unref === 'function') timer.unref()
-      return controller.signal
-    }
-    installed = true
-  }
-
-  return installed
-}
-
-/**
- * 浏览器侧垫片源码：由代理注入到 HTML <head>（在宿主所有脚本之前执行），
- * 为 iOS 16 / 旧 Safari / 旧 WebView（无 AbortSignal.any，Safari 17.4 才加入）
- * 上的 DSH 网页客户端补齐。多行可读源码，勿手工压缩成单行（配平易错）。
- */
-export const BROWSER_ABORT_SIGNAL_POLYFILL = `<script data-dsh-bridge-polyfill="2">
-!function () {
-  try {
-    var S = self.AbortSignal;
-    if (typeof S !== 'function') return;
-    if (typeof S.any !== 'function') {
-      S.any = function (signals) {
-        var list = Array.prototype.slice.call(signals || []);
-        var c = new self.AbortController();
-        var onAbort = function (ev) {
-          var src = ev && ev.target ? ev.target : ev;
-          cleanup();
-          try { c.abort(src ? src.reason : undefined); } catch (e) { c.abort(); }
-        };
-        var cleanup = function () {
-          for (var i = 0; i < list.length; i++) {
-            try { list[i].removeEventListener('abort', onAbort); } catch (e) {}
-          }
-        };
-        for (var i = 0; i < list.length; i++) {
-          if (list[i] && list[i].aborted) {
-            try { c.abort(list[i].reason); } catch (e) { c.abort(); }
-            return c.signal;
-          }
-        }
-        for (var i = 0; i < list.length; i++) {
-          try { list[i].addEventListener('abort', onAbort, { once: true }); } catch (e) {}
-        }
-        return c.signal;
-      };
-    }
-    if (typeof S.timeout !== 'function') {
-      S.timeout = function (ms) {
-        var c = new self.AbortController();
-        setTimeout(function () {
-          try { c.abort(new Error('The operation timed out.')); } catch (e) { c.abort(); }
-        }, Math.max(0, Number(ms) || 0));
-        return c.signal;
-      };
-    }
-  } catch (e) { /* 环境异常时不影响页面其余脚本 */ }
-}();
-</script>`
+// 运行时兼容垫片（lib/compat.js）
+//
+// 背景：DSH 核心依赖链（@deepseek-ai/dsh-timeout ← dsh-llm）在每次 agent 请求上
+// 调用 AbortSignal.any([...])，该 API 仅存在于 Node 20.3+/22+。运行在低版本 Node
+// （如 Node 18）上时，通过桥接发送消息会直接抛
+//   "AbortSignal.any is not a function ... (internal)"
+// 本模块在缺失时安装规范兼容的垫片；环境本身支持时不做任何事（返回 false）。
+//
+// 浏览器侧（旧 Safari/WebView）由 lib/index.js 的 HTML_HEAD_INJECTIONS 注入同语义垫片。
+
+function abortWith(controller, reason) {
+  try {
+    controller.abort(reason)
+  } catch {
+    try { controller.abort() } catch { /* 不可中止的信号：忽略 */ }
+  }
+}
+
+/**
+ * 在目标环境中安装 AbortSignal.any / AbortSignal.timeout 垫片（仅缺失时）。
+ * @param {object} [target] 可注入的环境（默认 globalThis），便于测试
+ * @returns {boolean} 是否实际安装了垫片
+ */
+export function installAbortSignalCompat(target = globalThis) {
+  const Signal = target.AbortSignal
+  const Controller = target.AbortController
+  if (!Signal || !Controller) return false
+
+  let installed = false
+
+  // ---- AbortSignal.any ----
+  if (typeof Signal.any !== 'function') {
+    Signal.any = (signals) => {
+      const list = Array.from(signals ?? [])
+      const controller = new Controller()
+      // 规范语义：任一源信号已中止 → 立即以该原因中止
+      for (const s of list) {
+        if (s && s.aborted) {
+          abortWith(controller, s.reason)
+          return controller.signal
+        }
+      }
+      const onAbort = (eventOrSignal) => {
+        // 真实 EventTarget 的 abort 事件参数是 event（event.target = 信号），
+        // 部分非标准实现直接传信号本身——两者都兼容取 reason
+        const src = eventOrSignal && eventOrSignal.target ? eventOrSignal.target : eventOrSignal
+        cleanup()
+        abortWith(controller, src ? src.reason : undefined)
+      }
+      const cleanup = () => {
+        for (const s of list) {
+          try { s.removeEventListener('abort', onAbort) } catch { /* 非标准信号：忽略 */ }
+        }
+      }
+      for (const s of list) {
+        try { s.addEventListener('abort', onAbort, { once: true }) } catch { /* 非标准信号：忽略 */ }
+      }
+      return controller.signal
+    }
+    installed = true
+  }
+
+  // ---- AbortSignal.timeout（Node 17.3+ / 较新浏览器才有，顺手补齐）----
+  if (typeof Signal.timeout !== 'function') {
+    Signal.timeout = (delayMs) => {
+      const controller = new Controller()
+      const delay = Math.max(0, Number(delayMs) || 0)
+      const reason = typeof target.DOMException === 'function'
+        ? new target.DOMException('The operation timed out.', 'TimeoutError')
+        : new Error('The operation timed out.')
+      const timer = setTimeout(() => abortWith(controller, reason), delay)
+      // 规范语义：timeout 信号的超时定时器不阻止进程退出
+      if (typeof timer.unref === 'function') timer.unref()
+      return controller.signal
+    }
+    installed = true
+  }
+
+  return installed
+}
+
+/**
+ * 浏览器侧垫片源码：由代理注入到 HTML <head>（在宿主所有脚本之前执行），
+ * 为 iOS 16 / 旧 Safari / 旧 WebView（无 AbortSignal.any，Safari 17.4 才加入）
+ * 上的 DSH 网页客户端补齐。多行可读源码，勿手工压缩成单行（配平易错）。
+ */
+export const BROWSER_ABORT_SIGNAL_POLYFILL = `<script data-dsh-bridge-polyfill="2">
+!function () {
+  try {
+    var S = self.AbortSignal;
+    if (typeof S !== 'function') return;
+    if (typeof S.any !== 'function') {
+      S.any = function (signals) {
+        var list = Array.prototype.slice.call(signals || []);
+        var c = new self.AbortController();
+        var onAbort = function (ev) {
+          var src = ev && ev.target ? ev.target : ev;
+          cleanup();
+          try { c.abort(src ? src.reason : undefined); } catch (e) { c.abort(); }
+        };
+        var cleanup = function () {
+          for (var i = 0; i < list.length; i++) {
+            try { list[i].removeEventListener('abort', onAbort); } catch (e) {}
+          }
+        };
+        for (var i = 0; i < list.length; i++) {
+          if (list[i] && list[i].aborted) {
+            try { c.abort(list[i].reason); } catch (e) { c.abort(); }
+            return c.signal;
+          }
+        }
+        for (var i = 0; i < list.length; i++) {
+          try { list[i].addEventListener('abort', onAbort, { once: true }); } catch (e) {}
+        }
+        return c.signal;
+      };
+    }
+    if (typeof S.timeout !== 'function') {
+      S.timeout = function (ms) {
+        var c = new self.AbortController();
+        setTimeout(function () {
+          try { c.abort(new Error('The operation timed out.')); } catch (e) { c.abort(); }
+        }, Math.max(0, Number(ms) || 0));
+        return c.signal;
+      };
+    }
+  } catch (e) { /* 环境异常时不影响页面其余脚本 */ }
+}();
+</script>`