dsh-remote-agent 0.9.2 → 0.9.4

package/lib/index.js

@@ -22,6 +22,10 @@
 import z from '@deepseek-ai/schemastery'
 import { applyHub, newNodeToken, normalizeConfig, NODE_UPGRADE_PATH, HEALTH_PATH } from './hub/index.js'
 import { registerSetupRoutes } from './setup-routes.js'
+// 配置分层（2026-10-18）：DSH 的插件管理器会重写 cordis.patch.yml、冲掉手工写的
+// 段（实测把我们的 role + webserver 整段删掉）。所以真正的配置另存一份在
+// <stateDir>/instance.json，加载时覆盖回来。见 lib/instance-config.js 头注释。
+import { mergeInstanceConfig } from './instance-config.js'
 
 /** 角色取值。 */
 export const ROLE = Object.freeze({ HUB: 'hub', WORKER: 'worker', BOTH: 'both', AUTO: 'auto' })
@@ -140,8 +144,39 @@ async function applyWorkerBranch(ctx, config, log) {
  * @param {object} [config] 行配置（profiles/*.cordis.yml 里的 config）
  */
 export function apply(ctx, config = {}) {
+  // ── 配置分层合并（2026-10-18，解决"配置被 DSH 重写冲掉"）──────────────
+  //
+  // 实测事故：用户在 DSH 里卸载重装插件后，`cordis.patch.yml` 从 3962B/15 条
+  // 被重写成 696B/4 条 —— **我们的 role 与 webserver 段整段消失**。DSH 的插件
+  // 管理器改依赖时会重写那个文件，只保留它自己管理的条目。
+  //
+  // 结果就是"每次设置完重启又回引导页"：写进去的 role 被外力冲掉，重启后
+  // 只剩包内默认（role: auto）。
+  //
+  // 所以配置分两层：
+  //   1. `cordis.patch.yml` 的 `- id: remote-agent` —— 只负责让 loader 加载
+  //   2. `<stateDir>/instance.json` —— 存真正的配置，**DSH 冲不掉**
+  //
+  // 这里把第 2 层合并进来，且**独立配置优先**（那是用户明确设置过的值）。
+  // 读失败/损坏时安静退回 loader config（配置读不出来不该让 DSH 起不来）。
+  const merged = mergeInstanceConfig(config)
+  if (merged.source) {
+    config = merged.config
+  }
+
   const { role, invalid, unconfigured } = resolveRoleDetail(config)
   const log = loggerOf(ctx)
+
+  // M3（2026-10-20）：独立配置优先，会**压住** loader（patch/插件 UI）里的同名字段。
+  // 这是设计（它才抗得住 DSH 重写），但必须留痕 —— 否则用户"改了 patch 没生效"
+  // 时完全无从判断。只记字段名，不记值（token 等敏感字段不能进日志）。
+  if (Array.isArray(merged.shadowed) && merged.shadowed.length > 0) {
+    log('info', 'instance.json overrides loader config (patch edits ignored for these keys)', {
+      keys: merged.shadowed,
+      fix: '要让 patch 生效，请删掉 instance.json 里对应的键（或用面板改）',
+    })
+  }
+
   // 配置写错必须有反馈。注意**不再回退 hub** —— 那会静默开一个
   // nodeToken 为空、不校验凭证的直连端点（见 resolveRoleDetail 的说明）。
   // 现在当成"未配置"处理：什么都不注册，面板显示引导让用户重选。
@@ -302,6 +337,22 @@ export const Config = z.object({
     uiPullRoot: z.string()
       .default('')
       .description('Web 面板拉取产物时唯一允许落地的目录（绝对路径）。留空则面板拉取按钮禁用。'),
+
+    // ── 独立监听（2026-10-18 引入，2026-10-20 补进 schema）───────────────
+    //
+    // ⚠ 这两个字段 0.9.3 就已在用，但**没有在这里声明** —— 靠 schemastery 的
+    // passthrough 才勉强能读到。后果：插件配置页里根本没有这两项（无表单）、
+    // 没有类型校验（`listenPort: "19387"` 会静默回弹默认值）、也无法在 UI 上改。
+    // 现在正式声明：能配、能校验、能在面板/插件页里看到。
+    listenHost: z.string()
+      .default('')
+      .description('独立监听绑定的具体本机 IP（留空=自动选：Tailscale > 私网 > 回环）。'
+        + '不能填 0.0.0.0 —— 通配地址会把服务暴露到所有网卡，且新版 DSH 同规则拒绝。'),
+    // 取值范围由 normalizeConfig 归一（0 <= port < 65536），这里只声明类型与默认值。
+    listenPort: z.number()
+      .default(19387)
+      .description('独立监听端口（副机从这里拨入）。0 = 关闭独立监听，只走 DSH 自己的 Web 服务通道。'),
+
     uiEnabled: z.boolean()
       .default(true)
       .description('是否注册 Web 面板的控制路由。'),

package/lib/instance-config.js

@@ -0,0 +1,261 @@
+/**
+ * 独立配置文件（2026-10-18，解决"配置被 DSH 重写冲掉"的根因）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 为什么需要它
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 实测事故（2026-10-18）：
+ *
+ *   01:44  cordis.patch.yml = 3962B / 15 条（含我们的 role + webserver）
+ *   12:05  cordis.patch.yml = 696B  /  4 条（**我们的段整段消失**）
+ *
+ * 12:05 前后用户在 DSH 里**卸载重装了插件**，同时 pnpm-lock.yaml 被更新。
+ * 结论：**DSH 的插件管理器在改动依赖时会重写 `cordis.patch.yml`，只保留它
+ * 自己管理的条目** —— 手工写的段会被冲掉。
+ *
+ * 这正是"每次设置完重启又回到引导页"的真正根因（不是版本旧、不是写错 profile）：
+ *
+ *   用户选角色 → 写入 cordis.patch.yml → 某次插件操作 → 我们的段被冲掉
+ *   → 重启 → role 消失 → 面板又显示引导
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 方案：配置分两层（本文件 = 不会被冲掉的那层）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ *   · **第 1 层**：`cordis.patch.yml` 里的 `- id: remote-agent` 行
+ *     —— 只负责"让 loader 加载这个插件"，内容可以极简（甚至只有 id + name）
+ *   · **第 2 层**：`<stateDir>/instance.json`（本文件管的这个）
+ *     —— 存 role / hubUrl / roots 等**真正的配置**
+ *
+ * loader 传进来的 config 与这里的值**合并**，后者在关键字段上**优先**
+ * （因为它是用户明确设置过、且不会被外力冲掉的）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 安全与边界
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ *   · 文件权限 0600（可能含 token）
+ *   · 原子写（tmp → rename），与 templates.js 同一套做法
+ *   · **绝不抛**：读失败/损坏时返回 null，让调用方退回 loader config
+ *     （配置读不出来不该让 DSH 起不来）
+ *   · 只存**白名单字段**，不存任意用户输入（防配置注入）
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/** 独立配置文件名（放在 stateDir 下）。 */
+export const INSTANCE_FILE_NAME = 'instance.json'
+
+/**
+ * 允许持久化的字段白名单。
+ *
+ * 为什么不直接存整个 config：config 里可能有 DSH 注入的东西（未知字段会
+ * 被 schemastery passthrough 保留），把它们写回磁盘等于把 loader 的中间态
+ * 固化下来。只存我们**真正需要跨重启保留**的。
+ *
+ * ⚠ 2026-10-20 补齐（v0.9.3 审查 H2/M2）：此前少了 `listenHost` /
+ * `listenPort` / `relay` —— 于是架构承诺"配置不会再被 DSH 冲掉"，
+ * 而 0.9.3 新增的两个关键字段恰好不在保护范围内，`relay`（跨 NAT 必需）
+ * 更是从来没有落过盘。用户配了它们，一次重启就静默回默认。
+ */
+const PERSISTED_KEYS = Object.freeze([
+  'role',
+  'nodeId',
+  'transportMode',
+  'hubUrl',
+  'relayUrl',
+  'roots',
+  'nodeToken',
+  'uiPullRoot',
+  'agentMode',
+  'pair',
+  // 0.9.3 独立监听的绑定意图（自动选地址会挑 Tailscale，用户可能想钉死局域网）
+  'listenHost',
+  'listenPort',
+  // hub 侧中继凭证（跨 NAT 场景的唯一通路）
+  'relay',
+])
+
+/** 值是对象的白名单字段（当前只有 relay：{ url, token }）。 */
+const OBJECT_KEYS = Object.freeze({
+  relay: ['url', 'token'],
+})
+
+/**
+ * 解析 stateDir（与 lib/node/index.js 的 resolveStateDir 同口径）。
+ * @param {object} [config]
+ * @returns {string}
+ */
+export function resolveStateDir(config) {
+  const c = config && typeof config === 'object' ? config : {}
+  const explicit = typeof c.stateDir === 'string' ? c.stateDir.trim() : ''
+  if (explicit !== '') {
+    try {
+      return path.resolve(explicit)
+    } catch {
+      /* 落到默认 */
+    }
+  }
+  try {
+    return path.join(os.homedir(), '.dsh-remote-agent')
+  } catch {
+    return path.join(os.tmpdir(), '.dsh-remote-agent')
+  }
+}
+
+/** 独立配置文件的绝对路径。 */
+export function instanceFilePath(config) {
+  return path.join(resolveStateDir(config), INSTANCE_FILE_NAME)
+}
+
+/**
+ * 字段级清洗（读与写共用，保证两侧对称）。
+ *
+ * 2026-10-20 扩展：支持 number（listenPort）与白名单对象（relay）。
+ * 早先只接受 string，于是 `listenPort: 19388` 这种合法配置会被静默丢弃。
+ *
+ * @param {Map<string, unknown>} src
+ * @returns {object|null} 清洗后的对象；没有任何有效字段时返回 null
+ */
+function sanitizeFields(src) {
+  const out = {}
+  for (const k of PERSISTED_KEYS) {
+    if (!src.has(k)) continue
+    const v = src.get(k)
+    if (v === null || v === undefined) continue
+
+    // roots：数组，去空去重前的简单清洗（真正的规范化在 normalizeRoots）
+    if (k === 'roots') {
+      if (Array.isArray(v)) {
+        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
+        if (arr.length > 0) out.roots = arr
+      }
+      continue
+    }
+
+    // relay：{ url, token } —— 只取白名单子键，且至少有一个非空
+    if (OBJECT_KEYS[k]) {
+      if (!v || typeof v !== 'object' || Array.isArray(v)) continue
+      const sub = {}
+      for (const sk of OBJECT_KEYS[k]) {
+        const sv = v[sk]
+        if (typeof sv === 'string' && sv.trim() !== '') sub[sk] = sv.trim()
+      }
+      if (Object.keys(sub).length > 0) out[k] = sub
+      continue
+    }
+
+    // listenPort：数字（0 合法 —— 表示显式关闭独立监听）
+    if (k === 'listenPort') {
+      const n = typeof v === 'number' ? v : (typeof v === 'string' && /^\d+$/.test(v.trim()) ? Number(v.trim()) : NaN)
+      if (Number.isInteger(n) && n >= 0 && n < 65536) out.listenPort = n
+      continue
+    }
+
+    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
+  }
+  return Object.keys(out).length > 0 ? out : null
+}
+
+/**
+ * 读独立配置。
+ *
+ * @param {object} [config] 用于解析 stateDir
+ * @returns {object|null} 读不到/损坏时返回 null（**不抛**）
+ */
+export function readInstanceConfig(config) {
+  const file = instanceFilePath(config)
+  let text
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch {
+    // ENOENT = 还没写过，是最常见的正常情况
+    return null
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    // 损坏：返回 null 让调用方退回 loader config（不让 DSH 起不来）
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+  return sanitizeFields(new Map(Object.entries(parsed)))
+}
+
+/**
+ * 写独立配置（原子写 + 0600）。
+ *
+ * @param {object} values 要写的字段（按白名单过滤）
+ * @param {object} [config] 用于解析 stateDir —— **必须传**，否则写默认目录、
+ *   而读的一方按 `config.stateDir` 找，两边对不上（v0.9.3 审查 M1 的成因）
+ * @returns {{ok:boolean, file:string, error?:string}}
+ */
+export function writeInstanceConfig(values, config) {
+  const dir = resolveStateDir(config)
+  const file = path.join(dir, INSTANCE_FILE_NAME)
+  const src = values && typeof values === 'object' ? values : {}
+  const out = sanitizeFields(new Map(Object.entries(src))) ?? {}
+
+  const tmp = `${file}.tmp-${process.pid}-${Date.now().toString(36)}`
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(tmp, `${JSON.stringify(out, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+    fs.renameSync(tmp, file)
+    return { ok: true, file }
+  } catch (err) {
+    try {
+      fs.rmSync(tmp, { force: true })
+    } catch {
+      /* 清理失败不掩盖原始错误 */
+    }
+    return { ok: false, file, error: String(err?.message ?? err) }
+  }
+}
+
+/**
+ * 把独立配置**合并进** loader 传进来的 config。
+ *
+ * ── 优先级（关键设计）──────────────────────────────────────────────────
+ *
+ * **独立配置优先** —— 因为：
+ *   · 它是用户通过面板明确设置过的值
+ *   · 它不会被 DSH 重写冲掉
+ *   · loader config 在"被冲掉"之后只剩包内默认（role: auto），
+ *     那正是"重启回引导页"的成因
+ *
+ * 例外：如果独立配置里**没有**某个字段，就用 loader config 的值。
+ *
+ * ⚠ 这个优先级有一个副作用（v0.9.3 审查 M3）：用户手改 `cordis.patch.yml`
+ * 或 DSH 插件 UI 之后，**同名字段永远不生效**，而且没有任何提示 ——
+ * 与项目反复强调的"面板说 A、插件实际做 B 是最难排查的撕裂"同型。
+ * 所以这里把"被覆盖了哪些字段"回报给调用方，由它记日志/在面板展示。
+ *
+ * @param {object} loaderConfig
+ * @param {object} [opts]
+ * @param {object} [opts.overlay] 读到的独立配置（避免重复读盘）
+ * @returns {{config:object, source:object|null, shadowed:string[]}}
+ *   `shadowed` = 独立配置压住 loader 值的字段名（值本身不回报，避免日志泄密）
+ */
+export function mergeInstanceConfig(loaderConfig, { overlay } = {}) {
+  const base = loaderConfig && typeof loaderConfig === 'object' ? loaderConfig : {}
+  let saved = overlay
+  if (saved === undefined) saved = readInstanceConfig(base)
+  if (!saved) return { config: base, source: null, shadowed: [] }
+
+  const shadowed = []
+  for (const k of Object.keys(saved)) {
+    if (!(k in base)) continue // loader 没有 → 不算"覆盖"，是补全
+    const a = base[k]
+    const b = saved[k]
+    // 只在**值真的不同**时记 —— 否则每次启动都刷一堆无意义的"覆盖"
+    const differ = (typeof a === 'object' || typeof b === 'object')
+      ? JSON.stringify(a) !== JSON.stringify(b)
+      : a !== b
+    if (differ) shadowed.push(k)
+  }
+  return { config: { ...base, ...saved }, source: saved, shadowed }
+}

package/lib/listen-server.js

@@ -0,0 +1,321 @@
+/**
+ * 独立监听端口（2026-10-18，解决"副机永远连不上"的架构级问题）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 为什么不再用 ctx.webServer
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 原实现把副机拨入端点注册在 DSH 的 `ctx.webServer` 上：
+ *
+ *     ctx.webServer.registerUpgrade({ path: '/api/remote-agent/node', handler })
+ *
+ * 于是副机必须能访问 **DSH 的 webserver 端口**。而那个端口的绑定地址来自
+ * DSH 自己的配置，带来两个无法绕开的死结：
+ *
+ *   1. **DSH 每次启动都重写 `<profile>/cordis.patch.yml`**（实测：写进去的
+ *      `webserver` 段在下一次启动时被删掉，只留 3 个 `ui-*` 条目）→ 绑回
+ *      `127.0.0.1` → 副机连不上。
+ *   2. `webServer` 服务**激活即 listen**，没有 rebind 方法 → 插件运行时改不了。
+ *
+ * 而且新版 `dsh-host-webserver` 硬拒绝 `0.0.0.0`（会直接让 DSH 启动崩溃）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 现在的做法：插件自己开一个端口
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 用 `node:http` 起一个独立的 server，自己处理 WebSocket 升级
+ * （复用 `lib/ws.js` 的 `acceptUpgrade` —— 和 DSH 内部用的是同一套底层实现）。
+ *
+ * 好处：
+ *   · **完全不依赖 DSH 的 webserver 配置**，DSH 怎么重写 patch 都不影响
+ *   · host/port 由插件自己的配置决定，可以持久化到 instance.json
+ *   · 不碰 DSH 的任何文件
+ *
+ * 代价：
+ *   · 多一个监听端口（默认 19387）
+ *   · 需要用户/配置告诉它绑哪个具体 IP（新版规则不允许 0.0.0.0，这本身是好事：
+ *     只绑用户指定的那张网卡，暴露面最小）
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 绑定地址怎么定（关键设计）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 无法绑 `0.0.0.0`（与新版 DSH 同一考量：通配地址把服务暴露到所有网卡）。
+ * 所以按以下优先级选一个**具体 IP**：
+ *
+ *   1. 配置里的 `listenHost`（用户显式指定，最高优先）
+ *   2. **Tailscale IP**（100.64.0.0/10 段）—— 本插件的目标场景就是跨机，
+ *      Tailscale 地址固定不变、跨网可达，是最合理的选择
+ *   3. 第一个私网 IPv4（192.168/10./172.16-31）
+ *   4. `127.0.0.1`（兜底：至少本机能连，同机 both 模式可用）
+ *
+ * **自动选 IP 是刻意的**：不让用户为了一个"该绑哪张网卡"去查 ipconfig。
+ */
+
+import http from 'node:http'
+import os from 'node:os'
+
+import { acceptUpgrade } from './ws.js'
+
+/** 默认端口：与历史行为一致（文档、配对码、用户既有配置都指向它）。 */
+export const DEFAULT_LISTEN_PORT = 19387
+
+/** Tailscale 的 CGNAT 段（100.64.0.0/10）。 */
+function isTailscaleIp(ip) {
+  if (typeof ip !== 'string') return false
+  const m = /^100\.(\d+)\./.exec(ip)
+  if (!m) return false
+  const second = Number(m[1])
+  // 100.64.0.0/10 → 第二段 64..127
+  return second >= 64 && second <= 127
+}
+
+/** 私网段。 */
+function isPrivateIp(ip) {
+  if (typeof ip !== 'string') return false
+  return (
+    ip.startsWith('192.168.') ||
+    ip.startsWith('10.') ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(ip)
+  )
+}
+
+/**
+ * 判定一个主机名/字面量地址是不是回环。
+ *
+ * ⚠ 这是**唯一的**回环判据（2026-10-20 收口）。此前 `lib/env-check.js` 的
+ * `isLoopbackOrigin`、`lib/hub/index.js` 的内联判断、`lib/client.js` 的前端
+ * 判断各写一份 —— 三份判据迟早分叉（C2 就是"两套地址分类"分叉的直接后果）。
+ * 新增调用方一律用这个，别再内联。
+ *
+ * @param {string} host 形如 `127.0.0.1` / `localhost` / `::1` / `[::1]`
+ * @returns {boolean}
+ */
+export function isLoopbackHost(host) {
+  if (typeof host !== 'string') return false
+  const h = host.trim().toLowerCase()
+  return h === '127.0.0.1' || h === 'localhost' || h === '::1' || h === '[::1]'
+}
+
+/** 一个地址的"可信程度"（0 最高）：Tailscale > RFC1918 > 其它。 */
+function scoreOf(address) {
+  if (isTailscaleIp(address)) return 0
+  if (isPrivateIp(address)) return 1
+  return 2
+}
+
+/**
+ * 列出本机所有非内网回环的 IPv4（按优先级排序）。
+ *
+ * @returns {Array<{address:string, family:string, iface:string, score:number}>}
+ */
+export function listCandidateAddresses() {
+  const out = []
+  let ifaces
+  try {
+    ifaces = os.networkInterfaces()
+  } catch {
+    return out
+  }
+  for (const [iface, list] of Object.entries(ifaces)) {
+    if (!Array.isArray(list)) continue
+    for (const info of list) {
+      if (!info || info.internal === true) continue
+      const family = info.family === 'IPv4' || info.family === 4 ? 'IPv4' : String(info.family)
+      if (family !== 'IPv4') continue
+      const address = typeof info.address === 'string' ? info.address : ''
+      if (address === '' || address.startsWith('169.254.')) continue // APIPA
+      // 优先级：Tailscale(0) > 私网(1) > 其它(2)
+      out.push({ address, family, iface, score: scoreOf(address) })
+    }
+  }
+  // 稳定排序（L6，2026-10-20）：同 score 时不能依赖 `os.networkInterfaces()`
+  // 的返回顺序 —— 那是平台相关的，同一台机器两次启动可能不同 → 绑定地址漂移。
+  // 用「接口名 → 地址」做次级键，保证同一台机器每次选出同一个地址。
+  out.sort((a, b) => (a.score - b.score)
+    || String(a.iface).localeCompare(String(b.iface))
+    || String(a.address).localeCompare(String(b.address)))
+  return out
+}
+
+/**
+ * 决定监听地址。
+ *
+ * @param {object} [o]
+ * @param {string} [o.listenHost] 用户显式配置的地址
+ * @param {string[]} [o.candidates] 覆盖候选列表（测试用）
+ * @returns {{host:string, source:string, candidates:Array}}
+ */
+export function resolveListenHost({ listenHost, candidates } = {}) {
+  const list = Array.isArray(candidates) ? candidates : listCandidateAddresses()
+
+  // 1. 用户显式指定（且不是通配地址 —— 新版规则不允许）
+  if (typeof listenHost === 'string') {
+    const h = listenHost.trim()
+    if (h !== '' && h !== '0.0.0.0' && h !== '::' && h !== '[::]') {
+      return { host: h, source: 'config', candidates: list }
+    }
+  }
+
+  // 2. Tailscale IP
+  const ts = list.find((x) => isTailscaleIp(x.address))
+  if (ts) return { host: ts.address, source: 'tailscale', candidates: list }
+
+  // 3. 私网 IP
+  const priv = list.find((x) => isPrivateIp(x.address))
+  if (priv) return { host: priv.address, source: 'private', candidates: list }
+
+  // 4. 任意非回环
+  if (list.length > 0) return { host: list[0].address, source: 'any', candidates: list }
+
+  // 5. 兜底：本机回环（同机 both 模式仍可用）
+  return { host: '127.0.0.1', source: 'loopback', candidates: list }
+}
+
+/**
+ * 启动一个只服务本插件 WS 端点的小 HTTP server。
+ *
+ * 只做两件事：
+ *   · `GET <healthPath>` → 200 JSON（运维自检用，不泄露敏感信息）
+ *   · `Upgrade: websocket` → 交给 `onUpgrade`（副机拨入）
+ *
+ * 其它路径一律 404 —— 这不是通用 web server，只承载节点端点。
+ *
+ * @param {object} o
+ * @param {string} o.host 绑定的具体 IP
+ * @param {number} o.port 端口（0 = 随机）
+ * @param {string} o.path WS 升级路径（必须精确匹配）
+ * @param {(conn:import('./ws.js').WSConnection, req:import('node:http').IncomingMessage)=>void} o.onUpgrade
+ * @param {string} [o.healthPath] 健康检查路径
+ * @param {object|((req:import('node:http').IncomingMessage)=>object)} [o.healthBody]
+ *   健康检查返回体；传函数可按调用者身份分级（匿名只回 `{ ok: true }`）
+ * @param {(level:string,msg:string,extra?:object)=>void} [o.log]
+ * @returns {Promise<{server:import('node:http').Server, host:string, port:number, close:()=>Promise<void>}>}
+ */
+export function startListenServer({
+  host,
+  port = DEFAULT_LISTEN_PORT,
+  path: upgradePath,
+  onUpgrade,
+  healthPath = '/healthz',
+  healthBody = { ok: true },
+  log = () => {},
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const sockets = new Set()
+
+    const server = http.createServer((req, res) => {
+      // 健康检查：给运维/体检一个"端口真的活着"的判据
+      try {
+        const url = new URL(req.url || '/', 'http://localhost')
+        if (req.method === 'GET' && url.pathname === healthPath) {
+          // healthBody 可以是对象，也可以是 `(req) => object`。
+          // 后者用于**按调用者身份分级**：匿名只回 `{ ok: true }`，
+          // 带正确口令才给插件名/角色/计数（v0.9.3 审查 L4 —— 这个端点
+          // 本来是无鉴权的，回 "plugin: dsh-remote-agent, role: hub"
+          // 等于给扫描器送指纹）。
+          let payload = healthBody
+          if (typeof healthBody === 'function') {
+            try {
+              payload = healthBody(req)
+            } catch (err) {
+              log('warn', 'health body threw', { error: String(err?.message ?? err) })
+              payload = { ok: false }
+            }
+          }
+          res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+          res.end(JSON.stringify(payload === undefined ? { ok: true } : payload))
+          return
+        }
+      } catch {
+        /* URL 解析失败：落到 404 */
+      }
+      res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })
+      res.end('not found\n')
+    })
+
+    // 追踪连接，close 时能强制断干净（否则旧连接会拖住 server.close）
+    server.on('connection', (socket) => {
+      sockets.add(socket)
+      socket.on('close', () => sockets.delete(socket))
+    })
+
+    server.on('upgrade', (req, socket, head) => {
+      let pathname
+      try {
+        pathname = new URL(req.url || '/', 'http://localhost').pathname
+      } catch {
+        socket.destroy()
+        return
+      }
+      // ⚠ 路径必须**精确匹配**：这个 server 只承载节点端点，
+      // 不开任何"顺手兼容一下"的口子（越宽的攻击面越难守）。
+      if (pathname !== upgradePath) {
+        socket.destroy()
+        return
+      }
+      const conn = acceptUpgrade(req, socket, head)
+      if (!conn) return
+      try {
+        onUpgrade(conn, req)
+      } catch (err) {
+        log('warn', 'upgrade handler threw', { error: String(err?.message ?? err) })
+        try {
+          conn.close(1011, 'internal error')
+        } catch {
+          /* 已关 */
+        }
+      }
+    })
+
+    // listen 失败要 reject（调用方会 log 并降级）；listen **之后**的错误则
+    // 只能用日志 —— 那个 Promise 早已 resolve，再 reject 是空操作。
+    // 2026-10-20 修（L1）：原实现无条件 reject，导致运行期 socket 错误全被吞掉。
+    let settled = false
+
+    server.on('error', (err) => {
+      // listen 失败（端口占用 / 地址不可用）要**明确报出来** ——
+      // 静默失败会让"副机连不上"变成又一个无头案。
+      if (!settled) {
+        settled = true
+        reject(err)
+        return
+      }
+      log('error', 'listen server error (runtime)', {
+        host,
+        port,
+        error: String(err?.message ?? err),
+        code: String(err?.code ?? ''),
+      })
+    })
+
+    server.listen(port, host, () => {
+      settled = true
+      const addr = server.address()
+      const actualPort = addr && typeof addr === 'object' ? addr.port : port
+      log('info', 'node endpoint listening', { host, port: actualPort, path: upgradePath })
+
+      const close = () => new Promise((done) => {
+        try {
+          server.close(() => done())
+        } catch {
+          done()
+        }
+        // 强制断开存量连接：server.close 只是"停止接受新连接"，
+        // 已有 WS 连接会一直挂着，插件卸载时不能留悬挂句柄。
+        for (const s of sockets) {
+          try {
+            s.destroy()
+          } catch {
+            /* 已关 */
+          }
+        }
+        sockets.clear()
+        // 兜底超时：某些平台 close 回调可能不触发
+        setTimeout(done, 2000).unref?.()
+      })
+
+      resolve({ server, host, port: actualPort, close })
+    })
+  })
+}