@qzsy/dsh-bridge 2.18.0 → 3.0.0

package/lib/restart-helper.mjs

@@ -1,133 +0,0 @@
-// 无托管器场景下的 DSH 重启助手（由 BridgeService.restartDsh 派生为独立进程）。
-//
-// 为什么需要它：旧进程调用 process.exit(0) 后，端口不会立刻释放；若新进程马上启动，
-// 很容易撞上 EADDRINUSE 然后无声退出（stdio 被 ignore 时连报错都看不到），
-// 结果就是"点了重启，dsh 再也没起来"。本助手按顺序做三件事并把过程写进日志：
-//   1. 等旧进程真正退出；
-//   2. 等端口释放（能连上说明还被占着）；
-//   3. 才派生新的 dsh，并在最长 120s 内确认端口可连接；失败则记日志并以非 0 退出。
-//
-// 用法（由 lib/index.js 组装 payload）：node restart-helper.mjs '<json>'
-import { spawn } from 'node:child_process';
-import { appendFileSync, openSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { connect } from 'node:net';
-
-const payload = JSON.parse(process.argv[2] ?? '{}');
-const {
-  pid, port, argv, cwd, execPath, logFile, childLog,
-  // 超时可注入（单测用），生产用默认值
-  waitTimeoutMs = 30_000,
-  readyTimeoutMs = 120_000,
-} = payload;
-const startedAt = Date.now();
-
-function log(message) {
-  try { appendFileSync(logFile, `[${new Date().toISOString()}] [helper] ${message}\n`); } catch { /* 日志不可写时忽略 */ }
-}
-
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-function processAlive(targetPid) {
-  try {
-    process.kill(targetPid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** 端口上是否有人在监听（能建立连接即视为被占用） */
-async function portAccepts(portNumber) {
-  return await new Promise((resolve) => {
-    let settled = false;
-    const done = (value) => { if (!settled) { settled = true; resolve(value); } };
-    let socket;
-    try {
-      socket = connect({ host: '127.0.0.1', port: portNumber });
-    } catch {
-      done(false);
-      return;
-    }
-    socket.setTimeout(1200);
-    socket.once('connect', () => { done(true); socket.destroy(); });
-    socket.once('timeout', () => { done(false); socket.destroy(); });
-    socket.once('error', () => { done(false); socket.destroy(); });
-  });
-}
-
-async function waitUntil(check, timeoutMs, label) {
-  const deadline = Date.now() + timeoutMs;
-  for (;;) {
-    if (await check()) return true;
-    if (Date.now() >= deadline) {
-      log(`等待超时：${label}（${timeoutMs}ms）`);
-      return false;
-    }
-    await sleep(400);
-  }
-}
-
-async function main() {
-  log(`启动：oldPid=${pid} port=${port} cwd=${cwd}`);
-
-  if (!(await waitUntil(() => !processAlive(pid), waitTimeoutMs, `旧进程 ${pid} 退出`))) {
-    log('旧进程仍在运行，放弃本次重启（不做任何破坏性动作）');
-    process.exit(2);
-  }
-  if (!(await waitUntil(async () => !(await portAccepts(port)), waitTimeoutMs, `端口 ${port} 释放`))) {
-    log(`端口 ${port} 仍被占用，放弃本次重启`);
-    process.exit(3);
-  }
-
-  let stdio = 'ignore';
-  try {
-    mkdirSync(dirname(childLog), { recursive: true });
-    stdio = openSync(childLog, 'a');
-  } catch { /* 打不开就用 ignore */ }
-
-  // spawn 的失败是异步 'error' 事件（例如 execPath 不存在 → ENOENT），只 try/catch 抓不到；
-  // 不挂监听会变成未捕获异常，而且父进程给助手设的是 stdio:'ignore' → 失败细节全部丢失。
-  // 这里挂监听并把原因写进日志，且**确认 spawn 成功后才**记录"已派生"。
-  const spawned = await new Promise((resolve) => {
-    let settled = false;
-    const settle = (value) => { if (!settled) { settled = true; resolve(value); } };
-    let child;
-    try {
-      const childEnv = { ...process.env };
-      if (process.platform !== 'win32') {
-        const execDir = dirname(execPath);
-        const defaultPaths = [execDir, '/usr/local/bin', '/usr/bin', '/bin'].filter(Boolean);
-        const existingPath = childEnv.PATH || '';
-        const missingPaths = defaultPaths.filter((p) => !existingPath.split(':').includes(p));
-        if (missingPaths.length > 0) {
-          childEnv.PATH = existingPath ? `${existingPath}:${missingPaths.join(':')}` : missingPaths.join(':');
-        }
-      }
-      child = spawn(execPath, argv, { cwd, env: childEnv, detached: true, stdio: ['ignore', stdio, stdio] });
-    } catch (err) {
-      log(`派生新 dsh 失败（同步异常）：${err?.message ?? err}`);
-      settle(null);
-      return;
-    }
-    child.once('error', (err) => {
-      log(`派生新 dsh 失败：${err?.message ?? err}`);
-      settle(null);
-    });
-    child.once('spawn', () => {
-      log(`已派生新 dsh：pid=${child.pid ?? '(未知)'}（输出见 ${childLog}）`);
-      settle(child);
-    });
-  });
-
-  if (!spawned) process.exit(4);
-  spawned.unref();
-
-  const up = await waitUntil(() => portAccepts(port), readyTimeoutMs, `新 dsh 监听 ${port}`);
-  log(up
-    ? `✅ 新 dsh 已就绪，耗时 ${Math.round((Date.now() - startedAt) / 1000)}s`
-    : `❌ 新 dsh 未能在 ${Math.round(readyTimeoutMs / 1000)}s 内就绪，请查看 ${childLog}`);
-  process.exit(up ? 0 : 1);
-}
-
-void main();

package/lib/security/log-sanitize.js

@@ -1,50 +0,0 @@
-// 日志值净化：防止日志注入（log injection / log forging）
-//
-// 背景（CodeQL js/log-injection）：日志里拼接的**外部可控字符串**（用户消息、
-// 远端返回的错误信息、文件名等）可能包含换行（`\n` / `\r`）与控制字符。攻击者一旦
-// 能注入换行，就能在日志文件里**伪造一整行新日志**（例如伪造一条"审批已通过"），
-// 也可以借超长单行撑爆日志采集器。
-//
-// 本模块只做一件事：把单行日志里要拼进去的动态值变成"一行且安全"。
-// 用法：logger.warn('... 失败: %s', sanitizeLogValue(err?.message))
-
-/**
- * 需要剔除的字符：C0 控制字符 + DEL + C1 控制字符。
- * 匹配控制字符正是本模块的**目的**，故显式豁免 no-control-regex。
- */
-// eslint-disable-next-line no-control-regex
-const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g
-
-/** 单条日志值默认最大长度（超出截断，避免超长输入撑爆日志/采集器） */
-export const LOG_VALUE_MAX_LEN = 500
-
-/**
- * 净化一个将写入日志的动态值。
- *
- * - 换行/回车 → 空格（保留可读性，同时杜绝伪造新行）
- * - 其它控制字符 → 直接剔除
- * - 超长截断并标注实际长度
- * - 非字符串安全转换（Error → message；对象 → JSON；null/undefined → ''）
- *
- * @param {unknown} value 原始值
- * @param {{ maxLen?: number }} [opts]
- * @returns {string} 可安全拼接进单行日志的字符串
- */
-export function sanitizeLogValue(value, { maxLen = LOG_VALUE_MAX_LEN } = {}) {
-  let text
-  if (value == null) return ''
-  if (typeof value === 'string') text = value
-  else if (value instanceof Error) text = value.message || value.name || 'Error'
-  else if (typeof value === 'object') {
-    try { text = JSON.stringify(value) } catch { text = String(value) }
-  } else text = String(value)
-
-  const oneLine = text
-    // 先折叠换行（含 \r\n，以及 U+2028/U+2029 这两个 Unicode 行分隔符）为一个空格
-    .replace(/[\r\n\u2028\u2029]+/g, ' ')
-    // 再剔除其余控制字符
-    .replace(CONTROL_CHARS, '')
-
-  const limit = Number.isFinite(maxLen) && maxLen > 0 ? maxLen : LOG_VALUE_MAX_LEN
-  return oneLine.length > limit ? `${oneLine.slice(0, limit)}…(${oneLine.length} chars)` : oneLine
-}

package/lib/security/path-validator.js

@@ -1,195 +0,0 @@
-// 跨平台文件系统与工作区路径安全校验模块
-// 防范任意路径遍历、系统关键目录越权与符号链接逃逸
-
-import { resolve, normalize, isAbsolute, basename } from 'node:path';
-import { homedir, platform } from 'node:os';
-import { stat, realpath } from 'node:fs/promises';
-
-const isWin = platform() === 'win32';
-
-// 敏感隐藏文件夹 / 文件名黑名单（全平台）
-const SENSITIVE_NAMES = new Set([
-  '.ssh',
-  '.gnupg',
-  '.aws',
-  '.azure',
-  '.kube',
-  '.git',
-  '.svn',
-  '.hg',
-  '.bash_history',
-  '.zsh_history',
-  '.profile',
-  '.bash_profile',
-  '.bashrc',
-  '.zshrc',
-  '.netrc',
-  'id_rsa',
-  'id_ed25519',
-  'id_ecdsa',
-  'id_dsa',
-  'credentials',
-  'shadow',
-  'passwd',
-  '.env',
-  '.npmrc',
-]);
-
-// Windows 系统敏感前缀
-const WIN_SYSTEM_PREFIXES = [
-  '\\\\', // UNC 路径限制
-  'windows',
-  'winnt',
-  'program files',
-  'program files (x86)',
-  'system volume information',
-  '$recycle.bin',
-  'recovery',
-  'perflogs',
-  'boot',
-  'programdata\\microsoft',
-];
-
-// POSIX 系统敏感前缀
-const POSIX_SYSTEM_PREFIXES = [
-  '/etc',
-  '/root',
-  '/sys',
-  '/proc',
-  '/dev',
-  '/boot',
-  '/lib',
-  '/lib64',
-  '/lib32',
-  '/usr/bin',
-  '/usr/sbin',
-  '/bin',
-  '/sbin',
-  '/private',
-  '/var/run',
-  '/var/root',
-];
-
-/**
- * 判断文件名/单级目录名是否属于敏感目录
- */
-export function isSensitiveFolderName(name) {
-  if (!name || typeof name !== 'string') return true;
-  const lower = name.toLowerCase().trim();
-  if (SENSITIVE_NAMES.has(lower)) return true;
-  if (/^(\$recycle\.bin|system volume information|\.ssh|\.gnupg|\.aws|\.git)$/i.test(lower)) return true;
-  return false;
-}
-
-/**
- * 校验路径是否安全可作为工作区或被远程浏览
- * @param {string} targetPath 目标路径
- * @param {object} options 配置项
- * @returns {Promise<{ valid: boolean, error?: string, path?: string, realPath?: string }>}
- */
-export async function isSafeWorkspacePath(targetPath, options = {}) {
-  if (!targetPath || typeof targetPath !== 'string') {
-    return { valid: false, error: '路径不能为空' };
-  }
-
-  const trimmed = targetPath.trim();
-  if (!trimmed || trimmed.includes('\0')) {
-    return { valid: false, error: '非法路径字符 (Null byte)' };
-  }
-
-  // 1. 基础路径归一化
-  let normalized;
-  try {
-    let raw = trimmed;
-    if (isWin && /^[A-Za-z]:$/.test(raw)) {
-      raw = `${raw}\\`;
-    }
-    normalized = normalize(resolve(raw));
-  } catch (err) {
-    return { valid: false, error: `路径解析失败: ${err.message}` };
-  }
-
-  const lowerNormalized = normalized.toLowerCase();
-
-  // 2. 检查 Windows 敏感路径
-  if (isWin) {
-    // 提取盘符后面的相对部分
-    const driveMatch = normalized.match(/^[A-Za-z]:\\(.*)$/);
-    if (driveMatch) {
-      const rest = driveMatch[1].toLowerCase();
-      for (const prefix of WIN_SYSTEM_PREFIXES) {
-        if (rest === prefix || rest.startsWith(`${prefix}\\`)) {
-          return { valid: false, error: `安全拦截：禁止访问系统敏感目录 (${prefix})` };
-        }
-      }
-    } else if (normalized.startsWith('\\\\')) {
-      return { valid: false, error: '安全拦截：禁止访问 UNC 网络共享路径' };
-    }
-  } else {
-    // 3. 检查 POSIX 敏感路径
-    for (const prefix of POSIX_SYSTEM_PREFIXES) {
-      if (lowerNormalized === prefix || lowerNormalized.startsWith(`${prefix}/`)) {
-        return { valid: false, error: `安全拦截：禁止访问系统关键目录 (${prefix})` };
-      }
-    }
-  }
-
-  // 4. 检查敏感隐藏目录片段（如路径中包含 /.ssh/ 或 \.ssh\）
-  const pathParts = normalized.split(/[\\/]/).filter(Boolean);
-  for (const part of pathParts) {
-    if (isSensitiveFolderName(part)) {
-      return { valid: false, error: `安全拦截：禁止访问敏感配置目录「${part}」` };
-    }
-  }
-
-  // 5. 校验物理文件系统状态与符号链接（Symlink）真实目标
-  let realTargetPath;
-  try {
-    const s = await stat(normalized);
-    if (!s.isDirectory()) {
-      return { valid: false, error: `指定路径不是文件夹: ${normalized}` };
-    }
-    realTargetPath = await realpath(normalized);
-  } catch (err) {
-    // 若仅是做路径规范性预校验（未必须已存在）
-    if (options.allowNonExistent) {
-      return { valid: true, path: normalized };
-    }
-    return { valid: false, error: `无法访问指定路径 (${err.message})` };
-  }
-
-  // 6. 对符号链接解析后的真实物理路径进行二次黑名单校验（防范符号链接逃逸）
-  if (realTargetPath && realTargetPath !== normalized) {
-    const realLower = realTargetPath.toLowerCase();
-    if (isWin) {
-      const realDriveMatch = realTargetPath.match(/^[A-Za-z]:\\(.*)$/);
-      if (realDriveMatch) {
-        const rest = realDriveMatch[1].toLowerCase();
-        for (const prefix of WIN_SYSTEM_PREFIXES) {
-          if (rest === prefix || rest.startsWith(`${prefix}\\`)) {
-            return { valid: false, error: `安全拦截：符号链接指向系统敏感目录 (${prefix})` };
-          }
-        }
-      }
-    } else {
-      for (const prefix of POSIX_SYSTEM_PREFIXES) {
-        if (realLower === prefix || realLower.startsWith(`${prefix}/`)) {
-          return { valid: false, error: `安全拦截：符号链接指向系统关键目录 (${prefix})` };
-        }
-      }
-    }
-
-    const realParts = realTargetPath.split(/[\\/]/).filter(Boolean);
-    for (const part of realParts) {
-      if (isSensitiveFolderName(part)) {
-        return { valid: false, error: `安全拦截：符号链接指向敏感配置目录「${part}」` };
-      }
-    }
-  }
-
-  return {
-    valid: true,
-    path: normalized,
-    realPath: realTargetPath || normalized,
-  };
-}

package/lib/security/rate-limiter.js

@@ -1,93 +0,0 @@
-// 滑动窗口请求速率限制器 (Rate Limiter)
-// 防范暴力破解、高频遍历与 DoS 攻击
-
-export class RateLimiter {
-  /**
-   * @param {object} options
-   * @param {number} options.maxRequests 窗口期内允许的最大请求数（默认 30）
-   * @param {number} options.windowMs 时间窗口毫秒数（默认 60000ms = 1分钟）
-   */
-  constructor({ maxRequests = 30, windowMs = 60000 } = {}) {
-    this.maxRequests = maxRequests;
-    this.windowMs = windowMs;
-    /** @type {Map<string, number[]>} key -> timestamp[] */
-    this.records = new Map();
-
-    // 定期清理过期记录（每 5 分钟清理一次）
-    this.cleanupTimer = setInterval(() => this.cleanup(), 5 * 60 * 1000);
-    if (this.cleanupTimer.unref) this.cleanupTimer.unref();
-  }
-
-  /**
-   * 检查指定 Key（如 IP / 用户 / Session）是否允许本次请求
-   * @param {string} key 限制标识
-   * @param {number} [customMax] 单次自定义最大请求数
-   * @returns {{ allowed: boolean, remaining: number, retryAfterSec: number }}
-   */
-  check(key = 'default', customMax) {
-    const limit = customMax || this.maxRequests;
-    const now = Date.now();
-    const windowStart = now - this.windowMs;
-
-    let timestamps = this.records.get(key);
-    if (!timestamps) {
-      timestamps = [];
-      this.records.set(key, timestamps);
-    }
-
-    // 过滤掉当前窗口期之前的记录
-    const valid = timestamps.filter(t => t > windowStart);
-    this.records.set(key, valid);
-
-    if (valid.length >= limit) {
-      const oldestInWindow = valid[0];
-      const resetTime = oldestInWindow + this.windowMs;
-      const retryAfterSec = Math.max(1, Math.ceil((resetTime - now) / 1000));
-      return {
-        allowed: false,
-        remaining: 0,
-        retryAfterSec,
-      };
-    }
-
-    valid.push(now);
-    return {
-      allowed: true,
-      remaining: limit - valid.length,
-      retryAfterSec: 0,
-    };
-  }
-
-  /**
-   * 重置指定 key 或全部记录
-   * @param {string} [key]
-   */
-  reset(key) {
-    if (key) this.records.delete(key);
-    else this.records.clear();
-  }
-
-  /**
-   * 清理所有过期记录
-   */
-  cleanup() {
-    const now = Date.now();
-    const windowStart = now - this.windowMs;
-    for (const [key, list] of this.records.entries()) {
-      const valid = list.filter(t => t > windowStart);
-      if (valid.length === 0) {
-        this.records.delete(key);
-      } else {
-        this.records.set(key, valid);
-      }
-    }
-  }
-
-  dispose() {
-    if (this.cleanupTimer) {
-      clearInterval(this.cleanupTimer);
-      this.cleanupTimer = null;
-    }
-    this.records.clear();
-  }
-}

package/lib/session-strip.js

@@ -1,100 +0,0 @@
-// DSH Bridge - 会话响应投影剥离（共享逻辑）
-//
-// contextHeaders / contextTimeline 是 DSH 会话投影里的两个大字段：每轮完整系统提示
-// + 工具定义（单会话 4.8MB+，session/list 数百会话可达 60MB+），但没有客户端 UI
-// 读取它们（会话打开时通过 WebSocket 实时获取，见 dsh-session-projection-cache 注释）。
-// 剥离后大幅降低传输体积（历史记录：session.history gzip 1.2MB -> ~150KB，约 8 倍；
-// 该端点已不在 DSH 0.2.1-rc.2 中，数字仅作收益量级参考）。
-//
-// 本模块被两个转发层复用：
-//   - tunnel-client.mjs（自建隧道）
-//   - index.js ProxyServer（局域网 / Cloudflare 隧道 / 外部隧道登记 —— 所有公网入口）
-// 命中失败（非 200 / 解析失败 / 结构不符）时原样返回，绝不破坏响应。
-//
-// DSH web 服务器默认开启 gzip 压缩（compression: gzip, level 1, threshold 1KB），
-// 所以 API 响应可能是 gzip 编码的。必须先解压才能 JSON.parse，否则解析失败，
-// catch {} 静默跳过剥离 → 完整 58MB+ 响应原样传输 → 隧道慢。
-
-import { gunzipSync } from 'node:zlib';
-
-// DSH 真实 RPC 路径是斜杠形式：dsh-client-connection 用 `${channel}/${endpoint}`
-// 拼 URL（channel=/api、endpoint=session/list），服务端 endpointFromPath 也按斜杠解析。
-// 点号形式可能是旧版/外部 REST 端点，保留以向后兼容（issue #82：此前只写点号，
-// 导致真实流量上剥离从未生效）。
-//
-// 关于 session/history（已核实，2026-10，DSH 0.2.1-rc.2）：
-//   该版本 dsh-api-session-controller 枚举出的 20 个 session 端点（见
-//   dsh-api-session-controller/lib/typert.remote-client.d.ts 与
-//   dsh-api-remotes/lib/client.js）只有 session/list、session/page、session/projections
-//   等，**没有 session/history**——会话历史读取走 session/page。
-//   因此斜杠 /api/session/history 在当前 DSH 版本上大概率是死路径；这里仍保留该分支
-//   作为兼容面（旧版本可能用过该端点，且外部/自定义网关可能仍以该路径转发），
-//   不因「当前版本无此端点」而删除。它只扩大命中集，不会误伤 session/page 等端点。
-const STRIP_PATHS = new Set([
-  '/api/session/list',
-  '/api/session/history', // 当前 DSH 0.2.1-rc.2 无此端点，保留兼容（见上）
-  '/api/session.list',
-  '/api/session.history',
-]);
-
-/**
- * 判断请求路径是否属于需要剥离会话投影的端点集合。
- * 同时兼容斜杠（DSH RPC 真实路径）与点号（历史 REST 路径）两种写法。
- * 注：session/list 是当前 DSH 版本的真实活端点；session/history 属兼容面
- * （DSH 0.2.1-rc.2 已无该端点，历史读取走 session/page），保留不删。
- * @param {string} pathname 请求路径，可带 query
- * @returns {boolean}
- */
-export function isSessionProjectionPath(pathname) {
-  const cleanPath = String(pathname || '').split('?')[0];
-  return STRIP_PATHS.has(cleanPath);
-}
-
-/**
- * 剥离 session/list（活端点）响应中的 contextHeaders 与 contextTimeline。
- * session/history 分支为兼容面（当前 DSH 0.2.1-rc.2 无该端点），结构同
- * projections.values，命中才会删除。
- * @param {string} pathname 请求路径（不含 query）
- * @param {Buffer} bodyBuf 原始响应体
- * @param {string} [contentEncoding] 响应的 content-encoding 头值（用于判断是否 gzip）
- * @returns {{ body: Buffer, stripped: boolean }} stripped=true 表示发生了剥离（调用方需更新 content-length 和 content-encoding）
- */
-export function stripSessionProjections(pathname, bodyBuf, contentEncoding) {
-  if (!isSessionProjectionPath(pathname) || !Buffer.isBuffer(bodyBuf)) {
-    return { body: bodyBuf, stripped: false };
-  }
-  try {
-    // 如果 DSH 服务器 gzip 压缩了响应，先解压再解析
-    const isGzipped = String(contentEncoding ?? '').toLowerCase() === 'gzip';
-    const parseBuf = isGzipped ? gunzipSync(bodyBuf) : bodyBuf;
-    const json = JSON.parse(parseBuf.toString('utf8'));
-    if (json?.result?.ok) {
-      const v = json.result.value;
-      let changed = false;
-      // session.list: items[].projections.values
-      if (v?.items) {
-        for (const item of v.items) {
-          const proj = item?.projections?.values;
-          if (proj && (proj.contextHeaders !== undefined || proj.contextTimeline !== undefined)) {
-            delete proj.contextHeaders;
-            delete proj.contextTimeline;
-            changed = true;
-          }
-        }
-      }
-      // session.history: projections.values
-      if (v?.projections?.values) {
-        const proj = v.projections.values;
-        if (proj.contextHeaders !== undefined || proj.contextTimeline !== undefined) {
-          delete proj.contextHeaders;
-          delete proj.contextTimeline;
-          changed = true;
-        }
-      }
-      if (changed) {
-        return { body: Buffer.from(JSON.stringify(json), 'utf8'), stripped: true };
-      }
-    }
-  } catch { /* 解析/解压失败则原样发送 */ }
-  return { body: bodyBuf, stripped: false };
-}

package/lib/sse-keepalive.js

@@ -1,115 +0,0 @@
-// SSE 空闲保活（issue #71）
-//
-// 背景：DSH 的 `/plugins/events` 等 `text/event-stream` 端点在首帧之后可以长时间
-// 不产生任何字节（宿主自身不发心跳）。经本插件反向代理出去的链路——局域网 3082、
-// Cloudflare 隧道、外部隧道登记、自建隧道本地腿——此前原样 pipe，链路空闲后会被
-// 中间设备按空闲流回收掐断。issue #71 实测：空闲的 /plugins/events 在 Cloudflare
-// 边缘 5/5 于 125.5–126.1s 被远端 cancel（cloudflared 日志 `stream ... canceled by
-// remote`），而每 ~20s 有帧流动的对照流全部存活；本机 dsh.ypbin.cn 独立复现同样
-// 在 126.9s 被掐。结果是远端面板实时通道每约 2 分钟断一次，必须手动刷新。
-//
-// 处理方式：对满足护栏条件的 SSE 响应，在代理侧静默超过
-// SSE_KEEPALIVE_INTERVAL_MS 时向客户端写入一帧 SSE 注释行 `: keepalive\n\n`。
-// SSE 规范（WHATWG EventSource）规定以 ':' 开头的行为注释、客户端必须忽略，
-// 因此对任何合规解析器零影响；本仓库 dsh-taskboard 的 `: ping` 已是同类先例。
-//
-// 三个安全护栏（缺一不注入，见 isSseKeepaliveCandidate）：
-//   1. content-type 必须是 text/event-stream —— 只碰真正的事件流；
-//   2. 未压缩（无 gzip/br/deflate content-encoding）——往压缩流里插明文会直接
-//      损坏字节流，客户端 gunzip 即报错；
-//   3. 无 content-length —— 定长响应插入额外字节会破坏消息帧界。
-//
-// 开关：ProxyServer 的 `sseKeepalive`（默认 true，cordis 配置 `sseKeepalive` 可关）。
-// 间隔固定 25s：远小于实测 126s 回收窗口，也低于常见 60s 空闲阈值；每 25s 仅
-// 12 字节，带宽代价可忽略。
-
-/** 保活帧：SSE 注释行，规范要求客户端忽略 */
-export const SSE_KEEPALIVE_FRAME = ': keepalive\n\n';
-
-/** 静默多久注入一帧（远小于 Cloudflare 实测 ~126s 空闲回收窗口） */
-export const SSE_KEEPALIVE_INTERVAL_MS = 25_000;
-
-/**
- * 判定一份上游响应头是否允许注入 SSE 保活帧。三条护栏见文件头注释。
- * @param {Record<string, string | string[] | undefined>} [headers] 上游响应头
- * @returns {boolean} true = 可以注入
- */
-export function isSseKeepaliveCandidate(headers = {}) {
-  const contentType = String(headers['content-type'] ?? '');
-  if (!contentType.toLowerCase().includes('text/event-stream')) return false;
-  // 定长响应绝不能插字节（消息帧界会被破坏）
-  if (headers['content-length'] !== undefined && headers['content-length'] !== null) return false;
-  // 压缩流绝不能插明文（会损坏 gzip/br 字节流）
-  const encoding = String(headers['content-encoding'] ?? '');
-  if (/(^|,\s*)(gzip|br|deflate)(\s*,|$)/i.test(encoding)) return false;
-  return true;
-}
-
-/**
- * 创建一个 SSE 空闲保活计时器。
- *
- * 语义：
- *   - 创建即开始第一段静默倒计时（上游首帧通常紧随其后，会重置计时）；
- *   - `poke()` 表示"刚见到上游数据"，从零重新起算静默窗口；
- *   - 静默满 intervalMs 写入一帧保活，并继续按 intervalMs 周期写（直到有数据或停止）；
- *   - `stop()` 幂等终止，之后 poke/写入均不再发生；
- *   - `write` 抛错视为连接已坏：停表且不向外抛（定时器回调里的异常会打崩事件循环），
- *     通过 onWriteError 上报，连接收尾由调用方的 close/error 负责。
- *
- * @param {object} options
- * @param {(frame: string) => void} options.write 写一帧的回调（调用方负责判断连接可写）
- * @param {number} [options.intervalMs] 静默间隔，默认 SSE_KEEPALIVE_INTERVAL_MS
- * @param {{ setTimeout: Function, clearTimeout: Function }} [options.timers] 可注入定时器（测试用）
- * @param {(err: unknown) => void} [options.onWriteError] 写失败回调
- * @returns {{ poke: () => void, stop: () => void, readonly stopped: boolean }}
- */
-export function createSseKeepalive(options = {}) {
-  const { write, intervalMs = SSE_KEEPALIVE_INTERVAL_MS, timers, onWriteError } = options;
-  if (typeof write !== 'function') throw new TypeError('createSseKeepalive: write 必须是函数');
-  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
-    throw new RangeError(`createSseKeepalive: intervalMs 必须是正数，收到 ${intervalMs}`);
-  }
-  const setT = timers?.setTimeout ?? globalThis.setTimeout;
-  const clearT = timers?.clearTimeout ?? globalThis.clearTimeout;
-
-  let timer = null;
-  let stopped = false;
-
-  const schedule = () => {
-    if (stopped) return;
-    timer = setT(() => {
-      timer = null;
-      if (stopped) return;
-      try {
-        write(SSE_KEEPALIVE_FRAME);
-      } catch (err) {
-        stopped = true;
-        try { onWriteError?.(err); } catch { /* 上报失败不得影响事件循环 */ }
-        return;
-      }
-      schedule();
-    }, intervalMs);
-  };
-
-  const poke = () => {
-    if (stopped) return;
-    // 从"最后一次见到上游数据"重新起算：清掉旧倒计时再排新的
-    if (timer !== null) clearT(timer);
-    schedule();
-  };
-
-  const stop = () => {
-    stopped = true;
-    if (timer !== null) {
-      clearT(timer);
-      timer = null;
-    }
-  };
-
-  schedule();
-  return {
-    poke,
-    stop,
-    get stopped() { return stopped; },
-  };
-}