dsh-remote-agent 0.9.2 → 0.9.3

package/lib/hub/index.js

@@ -16,6 +16,9 @@ import os from 'node:os'
 import path from 'node:path'
 import { ERROR_CODE, PROTOCOL_VERSION } from '../protocol.js'
 import { acceptUpgrade } from '../ws.js'
+// 独立监听端口（2026-10-18）：副机拨入不再依赖 DSH 的 webserver 配置
+// （DSH 每次启动重写 profile patch，会把 webserver 段冲掉）。
+import { DEFAULT_LISTEN_PORT, resolveListenHost, startListenServer } from '../listen-server.js'
 import { NodeRegistry } from './node-registry.js'
 import { RelayLink } from './relay-link.js'
 import { createPluginLogger } from './hub-util.js'
@@ -43,6 +46,20 @@ export function normalizeConfig(config = {}) {
   return {
     nodePath: typeof c.nodePath === 'string' && c.nodePath !== '' ? c.nodePath : NODE_UPGRADE_PATH,
     healthPath: typeof c.healthPath === 'string' && c.healthPath !== '' ? c.healthPath : HEALTH_PATH,
+    // ── 独立监听端口（2026-10-18）──────────────────────────────────────
+    //
+    // 副机拨入不再依赖 DSH 的 webserver（DSH 每次启动重写 profile patch，
+    // 会把 webserver 段冲掉；而且新版硬拒绝 0.0.0.0）。插件自己开端口。
+    //
+    // listenHost：留空 = **自动选**（Tailscale IP > 私网 IP > 回环）。
+    //   显式填了就按填的绑（必须是具体 IP，不能 0.0.0.0 —— 与 DSH 同规则）。
+    // listenPort：默认 19387（与历史配置、配对码、文档一致）。
+    listenHost: typeof c.listenHost === 'string' ? c.listenHost.trim() : '',
+    // listenPort：默认 19387（与历史配置、配对码、文档一致）。
+    // **0 = 显式关闭独立监听**（测试 / 只走 relay / 已在别处暴露端点时用）。
+    listenPort: Number.isFinite(c.listenPort) && c.listenPort >= 0 && c.listenPort < 65536
+      ? c.listenPort
+      : DEFAULT_LISTEN_PORT,
     nodeToken: typeof c.nodeToken === 'string' ? c.nodeToken : '',
     systemPrompt: c.systemPrompt !== false,
     // F1-1：healthz 是否暴露计数。默认 true（便于运维自检）；
@@ -383,7 +400,134 @@ export function applyHub(ctx, config = {}) {
     }, 'remote-agent: relay-link')
   }
 
-  // ── 直连 upgrade 路由 ─────────────────────────────────────────
+  // ── 独立监听端口（2026-10-18，**副机拨入的主通道**）───────────────────
+  //
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 为什么不再依赖 ctx.webServer
+  // ═══════════════════════════════════════════════════════════════════════════
+  //
+  // 原先副机端点注册在 `ctx.webServer.registerUpgrade` 上，于是副机必须能访问
+  // **DSH 自己的 webserver 端口**。这带来两个绕不开的死结：
+  //
+  //   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 启动崩溃，
+  // 我们踩过：10 份 crash 日志）。所以"帮用户把 webserver 改好"这条路是死的。
+  //
+  // ── 现在的做法 ──────────────────────────────────────────────────────────
+  //
+  // 插件自己用 `node:http` 起一个只服务节点端点的小 server（见
+  // lib/listen-server.js），**完全不依赖 DSH 的 webserver 配置**。
+  //
+  // 绑定地址自动选：配置的 listenHost > Tailscale IP > 私网 IP > 回环。
+  // 端口默认 19387（与历史配置、配对码、文档一致）。
+  //
+  // ⚠ 这是**新增的主通道**，不是替换：下面 webServer 的 registerUpgrade 仍然
+  // 保留 —— 老配置（webserver 恰好绑对了）的机器继续用那条路径，两条通道
+  // 并存不冲突（不同端口/不同 socket）。
+  let listenHandle
+  __reg(() => {
+    const listenHost = typeof cfg.listenHost === 'string' ? cfg.listenHost : ''
+    const port = Number.isFinite(cfg.listenPort) ? cfg.listenPort : DEFAULT_LISTEN_PORT
+
+    // ── `listenPort: 0` = 显式关闭独立监听（2026-10-18）────────────────
+    //
+    // 这个开关是**为测试与特殊部署**准备的：
+    //   · 单测/e2e 里 ctx 是 mock，本模块会真的开端口 → 监听句柄不释放
+    //     → 测试进程挂住（实测：hub-worker-e2e 90 秒不退出）。
+    //   · 某些部署场景（只走 relay、或已在别处暴露端点）不需要这个端口。
+    //
+    // 另外**自动检测测试环境**：测试不该真的占用 19387（并行跑多个测试文件
+    // 时还会互相抢端口，而且监听句柄不释放会让 `npm test` 挂住）。
+    //
+    // ⚠ 检测方式是 `NODE_TEST_CONTEXT`（node --test 会设为 'child-v8' 等），
+    // **不是** `process.argv` —— 实测 `node --test` 子进程的 argv 里没有
+    // `--test`（那是父进程的参数），第一版用 argv 判断所以没生效。
+    //
+    // 显式传非默认 listenPort 时以显式为准（有测试专门验证监听行为时要用）。
+    const isUnderTest = typeof process.env.NODE_TEST_CONTEXT === 'string'
+      && process.env.NODE_TEST_CONTEXT !== ''
+    const explicitPort = Number.isFinite(cfg.listenPort) && cfg.listenPort !== DEFAULT_LISTEN_PORT
+    if (port === 0 || (isUnderTest && !explicitPort)) {
+      log('info', 'independent listener disabled', {
+        reason: port === 0 ? 'listenPort: 0' : 'test environment (pass explicit listenPort to enable)',
+      })
+      return once(() => {})
+    }
+
+    const picked = resolveListenHost({ listenHost })
+    let disposed = false
+
+    startListenServer({
+      host: picked.host,
+      port,
+      path: cfg.nodePath,
+      healthPath: cfg.healthPath,
+      healthBody: {
+        ok: true,
+        plugin: 'dsh-remote-agent',
+        role: 'hub',
+        protocol: PROTOCOL_VERSION,
+        via: 'listen-server',
+      },
+      onUpgrade: (conn, req) => {
+        // 与 webServer 那条路完全相同的鉴权与交接逻辑（一处不能少：
+        // token 校验是这条通道唯一的口令，跳过就是一个无鉴权入口）。
+        if (cfg.nodeToken !== '') {
+          const token = req.headers['x-dsh-token']
+          if (!safeEqual(token, cfg.nodeToken)) {
+            log('warn', 'node upgrade rejected: bad token (listen-server)', { remote: remoteAddress(req) })
+            try {
+              conn.close(1008, 'bad token')
+            } catch {
+              /* 已关 */
+            }
+            return
+          }
+        }
+        registry.attachDirect(conn, { remote: remoteAddress(req) })
+      },
+      log,
+    })
+      .then((h) => {
+        if (disposed) {
+          // 竞态：disposer 先跑了（插件卸载/HMR），把刚起来的 server 关掉
+          void h.close()
+          return
+        }
+        listenHandle = h
+        log('info', 'node endpoint ready (independent listener)', {
+          host: h.host,
+          port: h.port,
+          source: picked.source,
+          path: cfg.nodePath,
+        })
+      })
+      .catch((err) => {
+        // ⚠ 监听失败不能静默：那会让"副机连不上"变成又一个无头案。
+        // 但要**降级而非抛出** —— 本插件不该把整个 DSH 拖垮
+        // （webServer 那条通道可能仍然可用）。
+        log('error', 'independent listener failed; falling back to webServer-only', {
+          host: picked.host,
+          port,
+          error: String(err?.message ?? err),
+          hint: '端口被占用或该地址不可用。可在插件配置里改 listenPort / listenHost。',
+        })
+      })
+
+    return once(() => {
+      disposed = true
+      if (listenHandle) {
+        void listenHandle.close()
+        listenHandle = undefined
+      }
+    })
+  }, 'remote-agent: independent-listener')
+
+  // ── 直连 upgrade 路由（保留：webServer 路径恰好可用的场景）─────────────
   __reg(() => {
     const dispose = ctx.webServer.registerUpgrade({
       path: cfg.nodePath,

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,6 +144,26 @@ 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)
   // 配置写错必须有反馈。注意**不再回退 hub** —— 那会静默开一个

package/lib/instance-config.js

@@ -0,0 +1,207 @@
+/**
+ * 独立配置文件（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 的中间态
+ * 固化下来。只存我们**真正需要跨重启保留**的。
+ */
+const PERSISTED_KEYS = Object.freeze([
+  'role',
+  'nodeId',
+  'transportMode',
+  'hubUrl',
+  'relayUrl',
+  'roots',
+  'nodeToken',
+  'uiPullRoot',
+  'agentMode',
+  'pair',
+])
+
+/**
+ * 解析 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)
+}
+
+/**
+ * 读独立配置。
+ *
+ * @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
+  // 字段级清洗（只取白名单，且去掉明显非法值）
+  const out = {}
+  for (const k of PERSISTED_KEYS) {
+    if (!(k in parsed)) continue
+    const v = parsed[k]
+    if (v === null || v === undefined) continue
+    // roots 是数组，单独清洗
+    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
+    }
+    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
+  }
+  return Object.keys(out).length > 0 ? out : null
+}
+
+/**
+ * 写独立配置（原子写 + 0600）。
+ *
+ * @param {object} values 要写的字段（按白名单过滤）
+ * @param {object} [config] 用于解析 stateDir
+ * @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 = {}
+  for (const k of PERSISTED_KEYS) {
+    if (!(k in src)) continue
+    const v = src[k]
+    if (v === null || v === undefined) continue
+    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
+    }
+    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
+  }
+
+  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 的值。
+ *
+ * @param {object} loaderConfig
+ * @param {object} [opts]
+ * @param {boolean} [opts.overlay] 读到的独立配置（避免重复读盘）
+ * @returns {{config:object, source:object|null}}
+ */
+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 }
+  return { config: { ...base, ...saved }, source: saved }
+}

package/lib/listen-server.js

@@ -0,0 +1,262 @@
+/**
+ * 独立监听端口（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)
+  )
+}
+
+/**
+ * 列出本机所有非内网回环的 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)
+      const score = isTailscaleIp(address) ? 0 : isPrivateIp(address) ? 1 : 2
+      out.push({ address, family, iface, score })
+    }
+  }
+  out.sort((a, b) => a.score - b.score)
+  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} [o.healthBody] 健康检查返回体
+ * @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) {
+          res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+          res.end(JSON.stringify(healthBody))
+          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 {
+          /* 已关 */
+        }
+      }
+    })
+
+    server.on('error', (err) => {
+      // listen 失败（端口占用 / 地址不可用）要**明确报出来** ——
+      // 静默失败会让"副机连不上"变成又一个无头案。
+      reject(err)
+    })
+
+    server.listen(port, host, () => {
+      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 })
+    })
+  })
+}

package/lib/setup-routes.js

@@ -35,6 +35,9 @@ import { writePatchBlock } from './setup.js'
 // 角色解析必须**只有一份实现** —— 面板说"未配置"而插件实际在跑 hub，
 // 是最难排查的撕裂（v0.7.0 踩过）。所以这里直接复用 lib/index.js 的解析器。
 import { resolveRoleDetail } from './index.js'
+// 配置分层（2026-10-18）：DSH 插件管理器会重写 cordis.patch.yml 并冲掉手工段，
+// 所以每次写配置时也在 <stateDir>/instance.json 存一份（插件加载时合并回来）。
+import { writeInstanceConfig, readInstanceConfig } from './instance-config.js'
 
 /** 引导路由的前缀。与 hub 的 `/api/remote-agent/ui` 分开 —— 未配置时后者不存在。 */
 export const SETUP_API_PREFIX = '/api/remote-agent/setup'
@@ -216,12 +219,28 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
     // `configured` 的语义是"用户已经做过选择，不需要引导"。
     // auto 也算已选择：它是个明确的工作模式（按 hubUrl 推断），不是"还没配"。
     const configured = role === 'auto' || detail.unconfigured !== true
+
+    // ── 独立配置状态（2026-10-18）──────────────────────────────────────
+    //
+    // 报告 `<stateDir>/instance.json` 里存了什么。这不是给用户看的细节，
+    // 而是排查"配置被 DSH 重写冲掉"这个坑的关键线索：
+    //   · instance 有值 = 配置抗住了重写（重启后 apply() 会合并回来）
+    //   · instance 为 null 但 patch 有值 = 只靠 patch 那层，下次重写会丢
+    const saved = readInstanceConfig(config)
     writeJson(res, 200, {
       ok: true,
       configured,
       // 推断结果（面板据此显示"当前生效角色"）—— auto 时它是有值的
       effectiveRole: detail.role,
       inferred: typeof detail.inferred === 'string' ? detail.inferred : '',
+      // 配置持久化的两层状态
+      persist: {
+        // DSH 会重写 cordis.patch.yml（实测会把我们的段整段冲掉）
+        patchFile: currentPatchFile(),
+        // 这一层 DSH 冲不掉，是"重启后配置还在"的真正保障
+        instanceFile: saved !== null,
+        instanceRole: saved && typeof saved.role === 'string' ? saved.role : null,
+      },
       // 回显当前配置里已有的值，方便用户"改一个字段"而不是从头填
       current: {
         role: typeof config.role === 'string' ? role : '',
@@ -342,12 +361,41 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
       })
     }
     log('info', 'setup applied', { role, file: result.file, mode: result.mode, warnings: applyWarnings })
+
+    // ── 同时写独立配置（2026-10-18，方案 B：防被 DSH 重写冲掉）──────────
+    //
+    // 事故：用户在 DSH 里卸载重装插件后，`cordis.patch.yml` 被重写成只剩
+    // 4 条 —— 我们的 role + webserver 整段消失，重启后又回引导页。
+    //
+    // 所以每次 setup 写入成功后，把**同样的值**再存一份到
+    // `<stateDir>/instance.json`。插件 `apply()` 时会把它合并回来
+    // （独立配置优先）。这样 DSH 怎么重写 patch 文件都不影响角色配置。
+    //
+    // 失败不阻塞：独立配置写不进去时，patch 文件那层仍然生效（只是不抗冲掉）。
+    const persisted = writeInstanceConfig({
+      role,
+      nodeId: str(body.nodeId),
+      transportMode: str(body.transportMode) || undefined,
+      hubUrl: str(body.hubUrl) || undefined,
+      relayUrl: str(body.relayUrl) || undefined,
+      roots,
+    })
+    if (persisted.ok !== true) {
+      applyWarnings.push(`独立配置写入失败（${persisted.error}）—— 角色配置仍写进了 patch 文件，`
+        + '但下次 DSH 重写该文件时可能丢失，建议重启后到面板确认一次。')
+      log('warn', 'instance config write failed', { file: persisted.file, error: persisted.error })
+    } else {
+      log('info', 'instance config persisted', { file: persisted.file })
+    }
+
     writeJson(res, 200, {
       ok: true,
       role,
       file: result.file,
       backup: result.backup,
       mode: result.mode,
+      // 独立配置的落点（让用户/排查者知道配置存在哪两处）
+      instanceFile: persisted.ok === true ? persisted.file : null,
       // 非致命提示（自动建目录的结果等）—— 面板要显示，否则用户以为
       // "目录已就绪"而实际没有
       warnings: applyWarnings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-agent",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "type": "module",
   "description": "把另一台电脑变成你 DSH 的远程 Agent 同事：副机本地持久跑任务、独立 Agent 循环，只回传 handoff 摘要与产物清单，成品按需拉取。",
   "license": "MIT",

package/scripts/check-doc-drift.mjs

@@ -1129,6 +1129,45 @@ check('65', 'eslint 严格档：lint script + 配置文件 + CI job 三件套齐
     'lib/client.js（dir: shareDir + nodeRoots UI）+ bin/dsh-remote-setup.js（envChecks）')
 }
 
+/* ── 86~87. 独立监听端口（2026-10-18，架构级修复）──
+ *
+ * 副机端点原来注册在 `ctx.webServer` 上 → 副机必须访问 DSH 的 webserver 端口。
+ * 而那个端口：
+ *   · **DSH 每次启动重写 profile patch**，把写进去的 `webserver` 段删掉
+ *     （实测：3962B/15 条 → 661B/3 条）→ 绑回 127.0.0.1 → 副机永远连不上
+ *   · `webServer` 激活即 listen，没有 rebind 方法
+ *   · 新版硬拒绝 0.0.0.0（会让 DSH 启动崩溃，踩过 10 份 crash 日志）
+ *
+ * 所以插件自己开一个 node:http server 服务节点端点，完全绕开 DSH 的 webserver。
+ * 这两条断言钉住"这条通道存在且不依赖 webServer"。
+ */
+{
+  const hubSrc2 = read('lib/hub/index.js')
+  const listenSrc = read('lib/listen-server.js')
+
+  check('86', '独立监听：插件自己开端口服务节点端点（不依赖 webServer 配置）',
+    /startListenServer/.test(hubSrc2)
+    && /resolveListenHost/.test(hubSrc2)
+    // 默认端口 19387（与历史配置/配对码/文档一致）
+    && /DEFAULT_LISTEN_PORT/.test(listenSrc)
+    && /19387/.test(listenSrc)
+    // 必须真的用 node:http 起 server（不是只 import 不用）
+    && /createServer/.test(listenSrc)
+    && /node:http/.test(listenSrc)
+    // 路径精确匹配（只承载节点端点，不做通用 web server）
+    && /pathname !== upgradePath/.test(listenSrc),
+    'lib/hub/index.js + lib/listen-server.js（node:http + acceptUpgrade + 精确路径）')
+
+  check('87', '独立监听：拒绝 0.0.0.0 + Tailscale 优先 + 测试环境不占端口',
+    // 拒绝通配地址（与新版 DSH 同规则；0.0.0.0 会让 DSH 崩溃，我们踩过）
+    /h !== '0\.0\.0\.0'/.test(listenSrc)
+    // 自动选地址时 Tailscale 优先（本插件的目标场景就是跨网）
+    && /isTailscaleIp/.test(listenSrc)
+    // 测试环境下不真的监听（否则 npm test 会挂住 —— 实测过）
+    && /NODE_TEST_CONTEXT/.test(hubSrc2),
+    'lib/listen-server.js（拒 0.0.0.0 + Tailscale 优先）+ hub/index.js（测试环境跳过）')
+}
+
 /* ── 输出 ── */
 const failed = results.filter((r) => !r.ok)
 if (process.argv.includes('--json')) {