@wenbin_wb/dsh-bridge 2.10.2 → 2.10.3

package/CHANGELOG.md

@@ -4,6 +4,33 @@
 
 ---
 
+## [v2.10.3] - 2026-09-03
+
+### ✨ 新功能
+
+- **兼容 DSH 原生端口直连（3080）**（issue #28）：此前本机用 `http://127.0.0.1:3080`（DSH 原生端口）打开面板时，因 loopback-token 端点仅暴露在代理端口 3082、且 CORS 白名单不含原生端口来源，管理功能会被误判为「远程」而锁定（local_only 策略下）。现在原生端口页面可跨域回读管理员令牌，直连与走代理行为一致；CORS 仍收敛，仅回显白名单来源。
+
+### 🐞 修复
+
+- **修复代理响应头透传问题**：反向代理与 WebSocket 升级路径现会剥离 hop-by-hop 头（transfer-encoding/connection 等），并对 WS 101 响应做白名单过滤，避免上游注入任意头或客户端解析异常。
+- **修复 QQ 流式消息发送**：首片失败时不再补发「全新流式消息」造成重复，直接降级单条 Markdown；引用机器人消息自动开新会话不再依赖固定 100ms 等待（消除竞态）。
+- **修复微信网关轮询竞态**：stop/restart 时通过 AbortController 立即中断进行中的长轮询，避免新旧 poller 并存触发 iLink 独占锁（403）。
+- **修复飞书群聊审批按钮被误拦**：群聊按「群」整体授权（与 QQ 群模型一致），群内成员可点按钮决议；单聊仍严格校验发起者本人。
+- **会话列表/历史大字段剥离覆盖全部公网入口**：session.list / session.history 的大字段剥离不再仅限自建隧道，Cloudflare 隧道、局域网、外部登记隧道同样生效（社区 PR #27 扩展）。
+
+### 🔒 安全
+
+- **[SEND_FILE] 外发白名单**：AI 输出携带的 `[SEND_FILE: 路径]` 指令现仅允许发送会话工作目录内的文件，并拦截 `.ssh`/`.credentials`/`.env` 等敏感路径，防止模型被诱导后外发任意本地文件。
+
+### 🧹 内部优化
+
+- **未设密码高危告警**：开启访问认证但尚未设置任何密码时，设置页顶部显示醒目风险提示。
+- **自建隧道安全须知**：README（中/英）明确隧道公网入口无独立认证、必须配合本地访问认证使用。
+- 版本探测失败改为 10 分钟退避重试；版本检查结果 10 分钟 TTL 缓存，减少外网请求。
+- 清理 Telegram 死代码（无调用点的审批卡片方法）。
+- 新增 issue #28 回归测试，全量单测通过。
+---
+
 ## [v2.10.2] - 2026-09-01
 
 ### ✨ 新功能

package/README.en.md

@@ -138,6 +138,8 @@ Access DeepSeek Harness from anywhere outside your home network without public I
 - **Mode 3: Custom WebSocket Tunnel**:
   - Connect to your personal VPS reverse proxy server ([View Setup Guide](docs/custom-tunnel.md)), equipped with per-message gzip and SSE optimization.
 
+> **Custom tunnel security note**: The tunnel server (`scripts/install-tunnel-server.sh`) only authenticates the *tunnel client control channel* with `TOKEN`; public HTTP/WebSocket requests forwarded through the tunnel domain are **not independently authenticated** — security relies entirely on the plugin's local Access Auth (the `x-dsh-internal-tunnel` marker prevents tunnel traffic from using the loopback exemption). Always enable **Access Auth** with a password/QR Token in the plugin settings (especially with `scope=all` or when exposed publicly); with no password set, anyone who knows the tunnel URL can reach your DSH.
+
 ---
 
 ### 3. 📱 Mobile Experience & Standalone PWA

package/README.md

@@ -146,6 +146,8 @@ dsh plugin --profile web add @wenbin_wb/dsh-bridge@latest
 - **模式 3：自建 WebSocket 隧道**
   * 支持连接个人 VPS 隧道中转服务器（[查看自建隧道部署教程](docs/custom-tunnel.md)），具备数据端到端 gzip 压缩与 SSE 响应优化。
 
+> **自建隧道安全须知**：隧道服务端（`scripts/install-tunnel-server.sh`）只对「隧道客户端控制通道」校验 `TOKEN`；公网访客对隧道域名的 HTTP/WebSocket 转发**不再做独立认证**，安全完全依赖插件本地的「访问认证」（`x-dsh-internal-tunnel` 标识使隧道流量无法享受本机回环保留）。请务必在插件设置中开启「安全认证」并设置访问密码/二维码 Token（尤其 `scope=all` 或公网使用时）；未设置任何密码时，任何知道隧道地址的访客都能直接访问您的 DSH。
+
 ---
 
 ### 3. 📱 移动端交互与 PWA 独立全屏 App

package/client/client.js

@@ -1993,7 +1993,31 @@ var AccessAuthCard = React.memo(function AccessAuthCard2({ auth, rpcCall, onUpda
           background: topMsg.ok ? "var(--dsw-alias-state-success-bg,#ecfdf5)" : "var(--dsw-alias-state-error-bg,#fef2f2)",
           color: topMsg.ok ? "var(--dsw-alias-state-success-primary,#059669)" : "var(--dsw-alias-state-error-primary,#dc2626)"
         }
-      }, topMsg.text)
+      }, topMsg.text),
+      // 访问认证已开启但尚未设置任何密码/Token 保护：局域网/公网访客可免密进入，高危提示
+      enabled && !auth?.hasPassword && !auth?.hasAdminPassword && React.createElement(
+        "div",
+        {
+          style: {
+            marginTop: 12,
+            padding: "10px 14px",
+            borderRadius: 6,
+            fontSize: 12,
+            background: "var(--dsw-alias-state-error-bg,#fef2f2)",
+            border: "1px solid var(--dsw-alias-state-error-border,#fecaca)",
+            color: "var(--dsw-alias-state-error-primary,#dc2626)",
+            lineHeight: 1.6
+          }
+        },
+        "\u26A0\uFE0F ",
+        React.createElement("strong", null, "\u5C1A\u672A\u8BBE\u7F6E\u4EFB\u4F55\u8BBF\u95EE\u5BC6\u7801\u6216\u7BA1\u7406\u5BC6\u7801"),
+        " \u2014\u2014 \u6B64\u65F6\u201C\u8BBF\u95EE\u8BA4\u8BC1\u5DF2\u5F00\u542F\u201D\u4F46\u4EFB\u4F55\u77E5\u9053\u5C40\u57DF\u7F51 IP / \u96A7\u9053\u5730\u5740\u7684\u4EBA\u90FD\u80FD\u76F4\u63A5\u8FDB\u5165\uFF08\u96A7\u9053\u5165\u53E3\u81EA\u8EAB\u4E0D\u8BBE\u9632\uFF0C\u8BE6\u89C1\u4E0B\u65B9\u5B89\u5168\u987B\u77E5\uFF09\u3002",
+        "\u5EFA\u8BAE\u7ACB\u5373\u5728\u4E0B\u65B9\u8BBE\u7F6E",
+        React.createElement("strong", null, "\u8BBF\u5BA2\u8BBF\u95EE\u5BC6\u7801"),
+        "\u6216",
+        React.createElement("strong", null, "\u7BA1\u7406\u5BC6\u7801"),
+        "\u540E\u518D\u5BF9\u5916\u5F00\u653E\u3002"
+      )
     ),
     React.createElement(
       React.Fragment,

package/client/index.js

@@ -943,6 +943,19 @@ const AccessAuthCard = React.memo(function AccessAuthCard({ auth, rpcCall, onUpd
           color: topMsg.ok ? 'var(--dsw-alias-state-success-primary,#059669)' : 'var(--dsw-alias-state-error-primary,#dc2626)',
         },
       }, topMsg.text),
+
+      // 访问认证已开启但尚未设置任何密码/Token 保护：局域网/公网访客可免密进入，高危提示
+      enabled && !auth?.hasPassword && !auth?.hasAdminPassword && React.createElement('div', {
+        style: {
+          marginTop: 12, padding: '10px 14px', borderRadius: 6, fontSize: 12,
+          background: 'var(--dsw-alias-state-error-bg,#fef2f2)',
+          border: '1px solid var(--dsw-alias-state-error-border,#fecaca)',
+          color: 'var(--dsw-alias-state-error-primary,#dc2626)',
+          lineHeight: 1.6,
+        },
+      }, '⚠️ ', React.createElement('strong', null, '尚未设置任何访问密码或管理密码'),
+        ' —— 此时“访问认证已开启”但任何知道局域网 IP / 隧道地址的人都能直接进入（隧道入口自身不设防，详见下方安全须知）。',
+        '建议立即在下方设置', React.createElement('strong', null, '访客访问密码'), '或', React.createElement('strong', null, '管理密码'), '后再对外开放。'),
     ),
 
     React.createElement(React.Fragment, null,

package/lib/feishu/node.js

@@ -182,8 +182,9 @@ export class FeishuConversationNode extends ConversationBridge {
       const outcome = action === 'approve' ? 'allowed-once' : 'rejected'
       const pending = this.pending.get(approvalId)
       if (pending) {
-        // 仅审批发起者可决议（与 /yes 的 senderId 校验同一防线）
-        if (pending.peerId && operatorId && pending.peerId !== operatorId) {
+        // 决议者校验：群聊按"群"整体授权（群内成员均可按钮决议，与 QQ 群模型一致），
+        // 不校验成员级 operatorId；单聊严格限定发起者本人（operatorId === 发起者 open_id）。
+        if (!pending.isGroup && pending.peerId && operatorId && pending.peerId !== operatorId) {
           this.logger?.warn?.('[dsh-bridge feishu] approval #%d blocked: operator %s is not the initiator %s', approvalId, operatorId, pending.peerId)
           return
         }
@@ -390,8 +391,13 @@ export class FeishuConversationNode extends ConversationBridge {
       }
       req.signal?.addEventListener('abort', onSignalAbort, { once: true })
 
-      // peerId 记录发起者：/yes 与卡片按钮都校验决议者身份
-      this.registerApproval(number, { number, request: req, resolve: resolveIm, timer, peerId: initiator })
+      // peerId 记录发起者：单聊 /yes 与卡片按钮都校验决议者身份；
+      // 群聊把"群"整体作为授权主体（首个 @ 即授权整群），群内成员均可决议，不校验成员级 operatorId
+      this.registerApproval(number, {
+        number, request: req, resolve: resolveIm, timer,
+        peerId: initiator,
+        isGroup: Boolean(peer.isGroup),
+      })
 
       let outcome
       try {

package/lib/index.js

@@ -26,6 +26,7 @@ import { TelegramService } from './telegram/index.js';
 import { AuthManager } from './auth/manager.js';
 import { renderLoginPage } from './auth/login-template.js';
 import { isSafeWorkspacePath, isSensitiveFolderName } from './security/path-validator.js';
+import { stripSessionProjections } from './session-strip.js';
 import { installAbortSignalCompat, BROWSER_ABORT_SIGNAL_POLYFILL } from './compat.js';
 
 const name = 'dsh-bridge';
@@ -245,6 +246,36 @@ function loopbackHeaders(headers, targetPort) {
   return out;
 }
 
+// hop-by-hop 响应头黑名单：这些头描述的是"当前一跳"的传输语义，反向代理
+// 透传会干扰客户端对响应体的解析（transfer-encoding/connection 并存、
+// keep-alive 连接复用错乱等）。Node http 层会自动生成正确的传输头，故统一剥离。
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+/**
+ * 净化上游响应头：剔除 hop-by-hop 头，返回可安全 writeHead 的干净头对象。
+ * 保留原始键大小写（Node writeHead 会归一化处理）。
+ * @param {object} headers 上游响应头（IncomingMessage.headers 形式）
+ * @param {Set<string>} [extra] 额外需剔除的头（小写）
+ */
+function sanitizeProxyHeaders(headers, extra) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (HOP_BY_HOP_HEADERS.has(k.toLowerCase())) continue;
+    if (extra && extra.has(k.toLowerCase())) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
 /**
  * HTTP + WebSocket 代理服务器（带安全认证守门）
  * 关键：改写 Host + Origin，注入 crypto.randomUUID polyfill
@@ -431,27 +462,42 @@ class ProxyServer {
         { host: '127.0.0.1', port: this.targetPort, method: req.method, path: req.url, headers, agent: false },
         (proxyRes) => {
           const contentType = String(proxyRes.headers['content-type'] ?? '');
-          // 未压缩的 HTML 文档注入 polyfill
-          if (contentType.includes('text/html') && !isCompressed(proxyRes.headers)) {
+          // 会话投影剥离（session.list / session.history）：这两个端点响应体可能达
+          // 数十 MB（contextHeaders 投影无 UI 读取），剥离后显著降低公网传输体积。
+          // 覆盖所有入口：局域网 / Cloudflare 隧道 / 外部隧道登记 / 自建隧道。
+          const isSessionProjection = pathname.startsWith('/api/session.list') || pathname.startsWith('/api/session.history');
+          const shouldBuffer = contentType.includes('text/html')
+            || (isSessionProjection && proxyRes.statusCode === 200 && !isCompressed(proxyRes.headers));
+          if (shouldBuffer) {
             const chunks = [];
             proxyRes.on('data', (c) => chunks.push(c));
             proxyRes.on('end', () => {
-              let html = Buffer.concat(chunks).toString('utf8');
-              if (!html.includes(INJECT_MARK)) {
-                html = html.replace(/<head[^>]*>/i, (m) => `${m}${HTML_HEAD_INJECTIONS}`);
-              }
-              const out = Buffer.from(html, 'utf8');
+              let out = Buffer.concat(chunks);
               const outHeaders = { ...proxyRes.headers };
+              if (contentType.includes('text/html') && !isCompressed(proxyRes.headers)) {
+                let html = out.toString('utf8');
+                if (!html.includes(INJECT_MARK)) {
+                  html = html.replace(/<head[^>]*>/i, (m) => `${m}${HTML_HEAD_INJECTIONS}`);
+                }
+                out = Buffer.from(html, 'utf8');
+              } else if (isSessionProjection) {
+                const { body, stripped } = stripSessionProjections(pathname, out);
+                if (stripped) out = body;
+              }
+              // 缓冲改写过 body：必须去掉原始传输头，避免 content-length 与
+              // transfer-encoding 并存导致客户端解析错误（HPE_INVALID_CONTENT_LENGTH）
               delete outHeaders['content-length'];
               delete outHeaders['transfer-encoding'];
               outHeaders['content-length'] = String(out.length);
-              res.writeHead(proxyRes.statusCode ?? 200, outHeaders);
+              res.writeHead(proxyRes.statusCode ?? 200, sanitizeProxyHeaders(outHeaders));
               res.end(out);
             });
             proxyRes.on('error', () => res.destroy());
             return;
           }
-          res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+          // 直通分支同样剔除 hop-by-hop 头（transfer-encoding/connection 等），
+          // 防止透传给客户端导致解析错误；Node 会按 writeHead+pipe 自动生成正确的传输头
+          res.writeHead(proxyRes.statusCode ?? 502, sanitizeProxyHeaders(proxyRes.headers));
           proxyRes.pipe(res);
           res.on('close', () => proxyRes.destroy());
           proxyRes.on('error', () => res.destroy());
@@ -481,8 +527,15 @@ class ProxyServer {
       });
       proxyReq.on('upgrade', (proxyRes, proxySocket, proxyHead) => {
         socket.write('HTTP/1.1 101 Switching Protocols\r\n');
+        // WS 升级成功：手写原始 socket 响应，只放行必要的 101 头（白名单），
+        // 避免上游注入任意头（如 set-cookie / 自定义敏感头）透传给浏览器
+        const WS_101_ALLOW = new Set([
+          'connection', 'upgrade', 'sec-websocket-accept',
+          'sec-websocket-extensions', 'sec-websocket-protocol',
+        ]);
         const raw = [];
         for (const [k, v] of Object.entries(proxyRes.headers)) {
+          if (!WS_101_ALLOW.has(k.toLowerCase())) continue;
           raw.push(`${k}: ${Array.isArray(v) ? v.join(', ') : v}`);
         }
         socket.write(`${raw.join('\r\n')}\r\n\r\n`);
@@ -500,7 +553,8 @@ class ProxyServer {
         if (proxyRes.statusCode === 101) return;
         try {
           const raw = [`HTTP/1.1 ${proxyRes.statusCode} ${proxyRes.statusMessage ?? ''}`.trim()];
-          for (const [k, v] of Object.entries(proxyRes.headers)) {
+          // 非 101（如后端拒绝升级）：剔除 hop-by-hop 头后再回写
+          for (const [k, v] of Object.entries(sanitizeProxyHeaders(proxyRes.headers))) {
             raw.push(`${k}: ${Array.isArray(v) ? v.join(', ') : v}`);
           }
           socket.end(raw.join('\r\n') + '\r\n\r\n');
@@ -574,6 +628,10 @@ class BridgeService {
     // DSH 宿主版本：惰性探测一次并缓存（进程生命周期内不变，避免频繁 spawn 子进程）
     this._dshVersion = null;
     this._dshVersionLoaded = false;
+    // 版本检查结果缓存（10 分钟 TTL）：客户端轮询/多处面板重复调用时不反复打 npm registry
+    this._versionCheckCache = null;
+    this._versionCheckCachedAt = 0;
+    this._versionCheckTtlMs = 10 * 60 * 1000;
   }
 
   /**
@@ -583,7 +641,9 @@ class BridgeService {
    */
   async getDshVersion() {
     if (this._dshVersionLoaded) return this._dshVersion;
-    this._dshVersionLoaded = true; // 只尝试一次，失败也不重试（避免每次 getStatus 都 spawn）
+    // 上次探测失败后的退避期未到：不 spawn，直接返回 null（面板仍可正常加载）
+    if (this._dshVersionRetryAt && Date.now() < this._dshVersionRetryAt) return this._dshVersion;
+    this._dshVersionLoaded = true; // 尝试期间置位；成功保持，失败在 catch 里复位并设退避
 
     const isWin = process.platform === 'win32';
     const nodeDir = dirname(process.execPath);
@@ -624,6 +684,10 @@ class BridgeService {
     } catch (e) {
       this.logger?.debug?.('dsh-bridge: 探测 DSH 版本失败: %s', e.message);
       this._dshVersion = null;
+      // 失败：复位已加载标记并设 10 分钟退避期。退避期内 getStatus 不再 spawn，
+      // 到期后允许重试一次（用户修复 PATH 后无需重启即可恢复版本显示）。
+      this._dshVersionLoaded = false;
+      this._dshVersionRetryAt = Date.now() + 10 * 60 * 1000;
     }
     return this._dshVersion;
   }
@@ -644,9 +708,14 @@ class BridgeService {
       targetPort: this.dshPort,
       authManager: this.authManager,
       logger: this.logger,
-      // loopback-token 允许跨域的面板来源：回环、当前局域网 IP、隧道公网地址
+      // loopback-token 允许跨域的面板来源：DSH 原生端口（直连 3080 场景）、代理端口、
+      // 当前局域网 IP、隧道公网地址。直连原生端口时页面相对路径拿不到 token，
+      // 必须允许它跨域回读 3082 代理端口的 loopback-token 端点（见 issue #28）。
       allowedOrigins: () => {
-        const origins = [`http://127.0.0.1:${this.proxyPort}`, `http://localhost:${this.proxyPort}`];
+        const origins = [
+          `http://127.0.0.1:${this.proxyPort}`, `http://localhost:${this.proxyPort}`,
+          `http://127.0.0.1:${this.dshPort}`, `http://localhost:${this.dshPort}`,
+        ];
         try {
           for (const iface of listAllLanIPv4()) origins.push(`http://${iface.address}:${this.proxyPort}`);
           if (this.selectedLanIp) origins.push(`http://${this.selectedLanIp}:${this.proxyPort}`);
@@ -915,6 +984,10 @@ class BridgeService {
 
   // 检查 npm 上是否有新版本（优先国内高速镜像 npmmirror，降级 npmjs 官方源）
   async checkVersion() {
+    // TTL 缓存：窗口内直接返回上次结果，避免重复请求外网 registry
+    if (this._versionCheckCache && Date.now() - this._versionCheckCachedAt < this._versionCheckTtlMs) {
+      return this._versionCheckCache;
+    }
     const fetchRegistry = (url, timeoutMs = 4000) => new Promise((resolve, reject) => {
       const req = httpsGet(url, { timeout: timeoutMs, headers: { 'User-Agent': 'dsh-bridge' } }, (res) => {
         if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode}`));
@@ -939,13 +1012,17 @@ class BridgeService {
     try {
       const latestData = await fetchRegistry('https://registry.npmmirror.com/@wenbin_wb/dsh-bridge/latest', 3500)
         .catch(() => fetchRegistry('https://registry.npmjs.org/@wenbin_wb/dsh-bridge/latest', 5000));
-      return {
+      const result = {
         current: VERSION,
         latest: latestData?.version ?? null,
         releaseNotes: latestData?.releaseNotes ?? null,
         dshVersion: await this.getDshVersion(),
       };
+      this._versionCheckCache = result;
+      this._versionCheckCachedAt = Date.now();
+      return result;
     } catch (e) {
+      // 失败不缓存（让下次调用可重试），但记录便于诊断
       return { current: VERSION, latest: null, error: e.message ?? '检查失败', dshVersion: await this.getDshVersion() };
     }
   }

package/lib/platform/conversation-bridge.js

@@ -21,7 +21,7 @@ import { randomUUID } from 'node:crypto'
 import { stat } from 'node:fs/promises'
 import { normalize } from 'node:path'
 import { resolveFilePath } from './message-split.js'
-import { splitForIM, textOfAssistantMessage, extractAndStripSendFileDirectives, extractFilePathsFromText } from './message-split.js'
+import { splitForIM, textOfAssistantMessage, extractAndStripSendFileDirectives, extractFilePathsFromText, isPathAllowedForSend } from './message-split.js'
 import { routeCommand } from './commands.js'
 import { listSessions, listWorkspaces, validateWorkspacePath, renderSessions, sessionsInDisplayOrder, describeTurnEnd, helpText, fmtTime, fmtSessionId, sessionLabel } from './session-catalog.js'
 
@@ -665,9 +665,14 @@ export class ConversationBridge {
             const uniqueFilesToSend = []
             for (const f of rawFiles) {
               const resolved = resolveFilePath(f, cwd)
-              if (resolved && !uniqueFilesToSend.includes(resolved)) {
-                uniqueFilesToSend.push(resolved)
+              if (!resolved || uniqueFilesToSend.includes(resolved)) continue
+              // 发送白名单：仅允许会话 cwd（及其子目录）内、且不命中敏感路径的文件，
+              // 防止模型被提示注入后借 [SEND_FILE] 外发 .ssh/.credentials/.env 等任意本地文件。
+              if (!isPathAllowedForSend(resolved, cwd)) {
+                this.logger?.warn?.(`[dsh-bridge ${this.platform.id}] blocked SEND_FILE outside allowed workspace: ${resolved}`)
+                continue
               }
+              uniqueFilesToSend.push(resolved)
             }
             for (const resolved of uniqueFilesToSend) {
               try {

package/lib/platform/message-split.js

@@ -2,7 +2,7 @@
 // 自 conversation-bridge.js 拆出：按平台 maxMessageChars 分块、保留 fenced code block、
 // [SEND_FILE: ...] 显式指令提取与路径解析。
 import { statSync } from 'node:fs'
-import { isAbsolute, normalize, resolve } from 'node:path'
+import { isAbsolute, normalize, relative, resolve } from 'node:path'
 
 const FENCE_RE = /^```([^\n`]*)\s*$/
 
@@ -149,6 +149,44 @@ export function resolveFilePath(rawPath, cwd = process.cwd()) {
   return null
 }
 
+/**
+ * 判断解析后的文件路径是否允许经 [SEND_FILE] 发送给 IM。
+ * 安全约束（防止模型被诱导后外发任意本地文件）：
+ *   1. 必须位于 allowedRoots 中的某个根目录（含子目录）内 —— 默认仅会话 cwd；
+ *   2. 路径任何一段不得命中敏感名单（.ssh/.gnupg/.aws/.git/.env/.credentials 等）。
+ * @param {string} resolvedPath 已解析的绝对路径
+ * @param {string|string[]} allowedRoots 允许的根目录（绝对路径）；默认 process.cwd()
+ * @returns {boolean}
+ */
+export function isPathAllowedForSend(resolvedPath, allowedRoots = process.cwd()) {
+  if (typeof resolvedPath !== 'string' || !resolvedPath) return false
+  const roots = Array.isArray(allowedRoots) ? allowedRoots : [allowedRoots]
+  if (roots.length === 0) return false
+
+  const normalized = resolve(resolvedPath)
+  const pathParts = normalized.split(/[\\/]/).filter(Boolean)
+  const SENSITIVE_PARTS = new Set([
+    '.ssh', '.gnupg', '.aws', '.azure', '.kube', '.git', '.svn', '.hg',
+    '.bash_history', '.zsh_history', '.profile', '.bash_profile', '.bashrc',
+    '.zshrc', '.netrc', '.env', '.npmrc', '.credentials', 'id_rsa', 'id_ed25519',
+    'id_ecdsa', 'id_dsa', 'shadow', 'passwd',
+  ])
+  for (const part of pathParts) {
+    if (SENSITIVE_PARTS.has(part.toLowerCase())) return false
+  }
+
+  for (const root of roots) {
+    if (typeof root !== 'string' || !root) continue
+    const normRoot = resolve(root)
+    if (normalized === normRoot) return true
+    // 用 relative 判断是否位于根内：越界时 rel 为 '..' 或以 '../' 开头
+    // （Windows 跨盘则 rel 是绝对路径，isAbsolute 拦截）。跨平台正确处理 \ 与 / 差异。
+    const rel = relative(normRoot, normalized)
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return true
+  }
+  return false
+}
+
 /**
  * 提取并过滤文本中的 [SEND_FILE: <path>] 显式发送指令
  * 由 AI 根据用户意图显式决定何时向用户发送文件附件，杜绝底层盲目扫描与误发。