dsh-remote-agent 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -9,6 +9,108 @@
 
 ---
 
+## [0.9.2] - 2026-10-18
+
+> **紧急修复：0.9.0/0.9.1 会让新版 DSH 启动崩溃。**
+> 如果你装了 0.9.x 并升级过 DSH（0.2.1-rc.2 及以后），**先升级到本版**。
+
+### 🔴 严重事故：包内 patch 绑 `host: '0.0.0.0'` 导致 DSH 启动崩溃
+
+**这是我的错。** 0.9.0 为了让"副机连得上"，在包内 patch 里加了：
+
+```yaml
+- id: webserver
+  config:
+    host: '0.0.0.0'
+    port: 19387
+```
+
+新版 `@deepseek-ai/dsh-host-webserver` 在 **schema 校验阶段**就硬拒绝通配地址：
+
+```
+webserver: host "0.0.0.0" is an unspecified (wildcard) address, which is not
+supported: binding every interface would expose remote code execution to the
+network; bind one concrete IPv4 or IPv6 address of a local interface instead
+```
+
+**后果链**：
+
+```
+webserver（required）激活失败
+  → webServer 服务缺失
+  → 至少 6 个插件排队等它
+    （web-runtime / open-in-app / directory-picker / client-hmr / remote-agent …）
+  → host 启动失败
+```
+
+实测在用户机器上产生 **10 份 crash 日志**（`crash-*.log`）。
+
+**这比它想修的"副机连不上"严重得多：连 DSH 都起不来了。**
+
+### 修复
+
+**包内 patch 不再碰 `webserver` 的任何字段。** 理由：
+
+1. `host` 必须是**具体某个本机接口地址**（Tailscale IP / 局域网 IP），
+   而这个值因人而异 —— 包里写死任何具体 IP 都是错的。
+2. 插件在 `apply()` 里**也不能**自己读网卡再拼配置：loader 的 patch 是
+   启动前静态合并的，改不了自己所在那一行的 config。
+3. 实际做法：**由用户在 profile 里配一次**，插件负责**检测并说清该怎么配**。
+
+配套修正（四处面向用户的文案，它们此前都在建议 `0.0.0.0`）：
+
+- `lib/env-check.js` 的 reachability 修法 → 改为"具体的本机 IP"，并明确警告
+  不能用 0.0.0.0，教会用户 `tailscale ip -4` / `ipconfig` 查地址
+- `lib/client.js` 的红色横幅 → 同上
+- `lib/hub/index.js` 的可达性自检 hint 与 log fix → 同上
+- `README.md` / `README.en.md` 的安装段 → 重写，把"必须绑具体 IP"讲清楚
+
+### 断言方向反转（79 / 新增 79b）
+
+**原来的断言 79 是错的** —— 它要求包内 patch **绑** `0.0.0.0`。现在反过来：
+
+- **79**：包内 patch 的**生效行**不得出现 `- id: webserver` 或
+  `host: '0.0.0.0'`，且必须把事故写进注释留档
+- **79b**：所有面向用户的修法文案都不得建议 `host: 0.0.0.0`，
+  且必须包含"不能用 0.0.0.0"的明确警告
+
+79 只扫**非注释行** —— 注释里必须保留事故原文（含 `0.0.0.0` 示例），
+那是给后来者的警示，不该被判违规。
+
+### 现在"副机连不上"怎么办
+
+包内 patch 不再代你配 `webserver`，所以**新装用户要自己填一次 host**。
+但这件事不再是静默失败：
+
+- 面板加载时**自动体检**，绑 loopback 会显示红色横幅
+- 「环境体检」里的 reachability 项会告诉你**当前绑在哪**、**该改成什么**
+- 提示里直接教怎么查自己的 IP
+
+**填什么**：
+
+```yaml
+- id: webserver
+  config:
+    host: '100.x.x.x'    # ← 换成你自己的地址（推荐 Tailscale IP）
+    port: 19387
+```
+
+查地址：`tailscale ip -4`（跨网，固定不变）或 `ipconfig`（同一局域网）。
+
+### 其他
+
+- 新增 `scripts/diag-worker.ps1` —— 副机诊断脚本（**只读**，不改任何文件），
+  输出 profile 列表、`remote-agent` 配置、插件版本、面板端点探测、
+  配置备份时间线。用于排查"每次重启都回到引导页"这类问题。
+
+```
+packaging   4 项
+doc-drift   121/121
+diag:inject 11 项
+tests       949（948 pass / 0 fail / 1 skip）
+lint        干净
+```
+
 ## [0.9.1] - 2026-10-17
 
 > **0.9.0 发布约 40 分钟后补发**。两个 High 都是真实功能失效

package/README.en.md

@@ -44,9 +44,16 @@ memory badges, task dispatch, task states, result summaries, workspace changes,
 change diffs (unified diffs of text-file edits), final artifacts, log tail,
 **environment health-check**, **workspace sharing (SMB)**, model dropdown.
 
-> **Works out of the box**: restart DSH after install and it just works. The
-> bundled patch defaults `role: auto` (no `hubUrl` ⇒ hub) and binds `webserver`
-> to `0.0.0.0:19387` (otherwise workers can never connect). See *Install* below.
+> **Works out of the box**: restart DSH after install and the bundled patch
+> defaults `role: auto` (no `hubUrl` ⇒ hub), which takes effect automatically.
+>
+> **For workers to connect, the hub's `webserver` must bind one concrete local
+> IP** (DSH binds `127.0.0.1` by default, which workers can never reach). You
+> fill this in once — the panel's *environment health-check* tells you exactly
+> what to put there.
+>
+> ⚠ **Never use `0.0.0.0`**: newer DSH rejects wildcard addresses and will
+> **fail to start**. See *Install* below.
 
 <p align="center">
   <img src="docs/screenshots/panel-main.png" width="720" alt="Web panel: nodes, dispatch form, task list">

package/README.md

@@ -42,7 +42,13 @@
 **工作区共享（SMB）**、模型下拉。
 
 > **开箱即用**：装完重启 DSH 就能用。包内 patch 默认 `role: auto`（没配
-> `hubUrl` 就是主机），并把 `webserver` 绑到 `0.0.0.0:19387`（否则副机连不上）。
+> `hubUrl` 就是主机），自动生效。
+>
+> **副机要能连上，主机的 `webserver` 必须绑一个具体的本机 IP**（DSH 默认只绑
+> `127.0.0.1`，那样副机永远连不上）。这一步需要你填一次 —— 打开面板时
+> 「环境体检」会检查并告诉你该填什么。
+>
+> ⚠ **不能用 `0.0.0.0`**：新版 DSH 会硬拒绝通配地址，导致 DSH **启动崩溃**。
 > 详见下方「安装」。
 
 <p align="center">
@@ -210,20 +216,41 @@ npm install -g dsh-remote-agent
 
 或在 DSH 的插件对话框里填 `github:zbzbhs/dsh-remote-agent`。
 
-**装完重启 DSH 就能用** —— 不需要改任何配置：
+**装完重启 DSH 就能用**：
 
 - 包内 patch 默认 `role: auto`。**没配 `hubUrl` 就是主机**，自动生效。
-- 包内 patch 把 `webserver` 绑到 `0.0.0.0:19387`，**副机才能连上**
-  （DSH 默认只绑 `127.0.0.1`，那样副机永远连不上且主机侧毫无异常）。
 - 打开 Web 面板「远程同事」，点「副机接入」生成配对码，发给副机。
 
-> **安全披露**：绑 `0.0.0.0` 意味着 **DSH 的整个 Web GUI 也能被局域网访问**
-> （不只是本插件的节点端点）。DSH 自带 Host/Origin 围栏 + 浏览器 cookie 鉴权，
-> 但暴露面确实变大了。如果你不需要跨机访问，可以在 profile 的
-> `cordis.patch.yml` 里覆盖回 `127.0.0.1` —— 但那样副机就连不上，
-> 请改用 [中继模式](profiles/README.md)。
+**唯一需要你填一次的是 `webserver` 的 host** —— 副机要能连上，主机必须绑一个
+**具体的本机 IP**（DSH 默认只绑 `127.0.0.1`，那样副机永远连不上，而且主机侧
+毫无异常）。在 profile 的 `cordis.patch.yml` 里：
+
+```yaml
+- id: webserver
+  config:
+    host: '100.x.x.x'    # ← 换成你自己的地址
+    port: 19387
+```
+
+**怎么查自己的地址**：
+
+- 跨网（推荐）：`tailscale ip -4` —— Tailscale IP 固定不变、跨网可达
+- 同一局域网：`ipconfig` 看 WLAN/以太网那块网卡的 IPv4
+
+> ⚠ **绝对不能写 `0.0.0.0`**。新版 `@deepseek-ai/dsh-host-webserver` 在 schema
+> 校验阶段就会硬拒绝通配地址：
+>
+> ```
+> host "0.0.0.0" is an unspecified (wildcard) address, which is not supported:
+> binding every interface would expose remote code execution to the network;
+> bind one concrete IPv4 or IPv6 address of a local interface instead
+> ```
+>
+> 后果是 **DSH 启动崩溃**（`webserver` 是 required 插件，它挂了 `webServer`
+> 服务就缺失，至少 6 个插件排队等它，包括本插件）。
 >
-> 面板的「体检」按钮会明确告诉你当前绑在哪（面板加载时也会自动体检一次）。
+> 面板的「环境体检」会自动检测这一项，绑错了会明确告诉你当前绑在哪、
+> 该改成什么 —— 面板加载时也会自动体检一次。
 
 ### 副机（worker）—— 贴个配对码就行
 

package/cordis.patch.yml

@@ -99,36 +99,43 @@
         role: auto
 
 # ═══════════════════════════════════════════════════════════════════════════
-# 让 hub 真的能被外部访问（2026-10-17，**这是"开箱即用"的关键一条**）
+# ⚠⚠ 绝对不要覆盖 webserver 的 host（2026-10-18 事故：我犯过这个错）
 # ═══════════════════════════════════════════════════════════════════════════
 #
-# ── 为什么必须改 webserver ──────────────────────────────────────────────
+# ── 事故经过 ────────────────────────────────────────────────────────────
 #
-# 本插件的副机要主动连主机：`ws://<主机IP>:19387/api/remote-agent/node`。
-# 而那个 WebSocket upgrade 是注册在 DSH 的 `ctx.webServer` 上的
-# （`ctx.webServer.registerUpgrade(...)`）—— **没有独立端口选项**。
+# v0.9.0 为了让"副机连得上"，我在包内 patch 里加了：
 #
-# 而 DSH 的 `@deepseek-ai/dsh-host-webserver` 的 `host` 是必填项、无默认值，
-# 且它面向的默认场景是"本机浏览器访问自己"，所以多数 profile 绑 127.0.0.1。
+#     - id: webserver
+#       config:
+#         host: '0.0.0.0'
+#         port: 19387
+#
+# **结果：DSH 直接启动崩溃。** 新版 `@deepseek-ai/dsh-host-webserver` 在
+# schema 校验阶段就硬拒绝通配地址：
+#
+#     webserver: host "0.0.0.0" is an unspecified (wildcard) address, which is
+#     not supported: binding every interface would expose remote code execution
+#     to the network; bind one concrete IPv4 or IPv6 address of a local
+#     interface instead
+#
+# 后果链：webserver（required）激活失败 → `webServer` 服务缺失 → 至少 6 个
+# 插件排队等它（web-runtime / open-in-app / directory-picker / client-hmr /
+# **remote-agent** …）→ host 启动失败。实测产生了 10 份 crash 日志。
 #
-# 结果：不覆盖这一行，hub 只监听 loopback → **副机永远连不上**，而主机侧
-# 毫无异常（healthz 200、面板能开、工具都在）。用户只能猜"地址错了？
-# token 错了？防火墙？" —— 2026-10-17 实测踩到，代价是好几轮排查。
+# 这个错误比它想修的"副机连不上"严重得多：**连 DSH 都起不来了**。
 #
-# ── 安全披露（必须让用户知道）──────────────────────────────────────────
+# ── 所以现在的做法 ──────────────────────────────────────────────────────
 #
-# 绑 0.0.0.0 意味着 **DSH 的整个 Web GUI 也能被局域网访问**（不只是我们的
-# 节点端点）。DSH 自带 Host/Origin 围栏 + 浏览器 cookie 鉴权，但暴露面确实
-# 变大了。所以：
-#   · README 与面板都有明确提示
-#   · 环境体检把这条列出来
-#   · 用户可在 profile 里覆盖回 127.0.0.1（此时请改用 relay 模式，否则副机连不上）
+# **本包不碰 webserver 的任何字段。** 理由：
 #
-# ── 优先级 ──────────────────────────────────────────────────────────────
+#   1. host 必须是**具体某个本机接口地址**（如 Tailscale IP / 局域网 IP），
+#      而这个值因人而异 —— 包里写死任何具体 IP 都是错的。
+#   2. 插件在 `apply()` 里也**不能**自己读网卡再拼配置：loader 的 patch 是
+#      启动前静态合并的，改不了自己所在那一行的 config。
+#   3. 实际做法：**主机的 webserver 由用户/DSh 自己配**，我们只在
+#      「环境体检」里检测"是否绑在可达地址"，绑 loopback 就明确报错并给出
+#      该填什么（含如何查自己的 Tailscale / 局域网 IP）。
 #
-# `cordis.yml` 头注释：应用顺序是 bundles → cordis.patch.yml → --patch overlays。
-# 所以**用户 profile 里的同名行会覆盖这里**（用户优先，符合预期）。
-- id: webserver
-  config:
-    host: '0.0.0.0'
-    port: 19387
+# 这就是 0575c6b 的可达性自检 + c4459c5 的环境体检的价值 —— **诊断而不是
+# 代改配置**。2026-10-17 我想"帮用户改好"，结果改出了启动崩溃。

package/lib/client.js

@@ -1736,8 +1736,15 @@ window.__ModuleLoader__.load({
           h('div', null, '现在监听在 ', h('code', null, reach.origin || ''),
             '，只有本机能访问。副机用任何地址都连不上。'),
           h('div', { style: { marginTop: '6px' } }, '修法：在 profile 的 ',
-            h('code', null, 'cordis.patch.yml'), ' 里给 ', h('code', null, 'webserver'),
-            ' 行加 ', h('code', null, "host: '0.0.0.0'"), '（保留 port），然后重启 DSH。'),
+            h('code', null, 'cordis.patch.yml'), ' 里把 ', h('code', null, 'webserver'),
+            ' 的 ', h('code', null, 'host'), ' 改成一个具体的本机 IP，然后重启 DSH。'),
+          // ⚠ 修法**不能写 0.0.0.0**（2026-10-18 事故）：新版 dsh-host-webserver
+          // 在 schema 校验阶段就拒绝通配地址，会让 **DSH 启动崩溃**
+          // （webserver 是 required 插件）。必须绑一个具体的本机接口地址。
+          h('div', { className: 'dra-dim', style: { marginTop: '2px' } },
+            '⚠ 不能用 0.0.0.0 —— 新版 DSH 会拒绝并导致启动失败。'
+            + '查地址：Tailscale 用 tailscale ip -4，局域网用 ipconfig。'
+            + '推荐绑 Tailscale IP（固定不变、跨网可达）。'),
           reach.hint
             ? h('div', { className: 'dra-dim', style: { marginTop: '4px' } }, reach.hint)
             : null,

package/lib/env-check.js

@@ -206,11 +206,30 @@ export function envChecks({
           // 修法给**可直接粘贴的片段**（v0.9.0 审查 L3：不假装有一键修复）。
           // 这是用户 profile 的配置，插件客观上不能静默代改 ——
           // 用户 profile 优先于包内 patch 是明确的设计。
-          fix: "在 profile 的 cordis.patch.yml 里加下面这段（或把已有的 webserver 行改成它），然后重启 DSH：\n"
-            + "  - id: webserver\n"
-            + "    config:\n"
-            + "      host: '0.0.0.0'\n"
-            + "      port: 19387",
+          //
+          // ⚠ **绝对不要建议 `0.0.0.0`**（2026-10-18 事故）。
+          //
+          // 新版 `dsh-host-webserver` 在 schema 校验阶段就硬拒绝通配地址：
+          //   host "0.0.0.0" is an unspecified (wildcard) address, which is not
+          //   supported: binding every interface would expose remote code
+          //   execution to the network; bind one concrete IPv4 or IPv6 address
+          //   of a local interface instead
+          //
+          // 后果是 **DSH 启动崩溃**（webserver 是 required 插件，它挂了
+          // `webServer` 服务就缺失，至少 6 个插件排队等它）。v0.9.0 曾把这个
+          // 建议写进包内 patch，实测产生 10 份 crash 日志。
+          //
+          // 正确做法：绑**一个具体的本机接口地址**。推荐 Tailscale IP ——
+          // 它固定不变、跨网可达，正好是本插件的使用场景。
+          fix: '把 profile 的 cordis.patch.yml 里 webserver 的 host 改成'
+            + '**一个具体的本机 IP**（不能用 0.0.0.0 —— 新版 DSH 会拒绝并启动失败），'
+            + '然后**重启 DSH**。\n'
+            + '  查地址：Tailscale 用 `tailscale ip -4`，局域网用 `ipconfig`。\n'
+            + '  推荐绑 Tailscale IP（固定不变、跨网可达）：\n'
+            + '  - id: webserver\n'
+            + '    config:\n'
+            + "      host: '<你的具体 IP，例如 100.x.x.x>'\n"
+            + '      port: 19387',
           detail: loop
             ? `当前只监听 ${reachability.bound || '127.0.0.1'}（${reachability.origin || ''}）—— 副机用任何地址都连不上`
             : `当前监听 ${reachability.origin || ''}`,

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（便于运维自检）；
@@ -305,14 +322,17 @@ export function applyHub(ctx, config = {}) {
         origin,
         loopback,
         hint: loopback
-          ? "webServer 绑在 loopback，副机无法接入。在 profile 的 cordis.patch.yml 里给 webserver 行加 host: '0.0.0.0'（保留 port），然后重启 DSH。"
+          // ⚠ 不能建议 0.0.0.0（2026-10-18 事故）：新版 dsh-host-webserver 在
+          // schema 校验阶段就拒绝通配地址 → webserver 无法激活 → webServer
+          // 服务缺失 → DSH 启动崩溃。必须绑一个**具体的本机接口地址**。
+          ? 'webServer 绑在 loopback，副机无法接入。在 profile 的 cordis.patch.yml 里把 webserver 的 host 改成一个具体的本机 IP（推荐 Tailscale IP：tailscale ip -4），然后重启 DSH。不能用 0.0.0.0 —— 新版 DSH 会拒绝并启动失败。'
           : '',
       }
       if (loopback) {
         log('warn', 'hub 绑在 loopback：副机将无法接入', {
           origin,
           bound: hostname,
-          fix: "给 webserver 加 host: '0.0.0.0'",
+          fix: "把 webserver 的 host 改成具体的本机 IP（如 Tailscale IP），不能用 0.0.0.0",
         })
       } else {
         log('info', 'hub reachable from other hosts', { origin, bound: hostname })
@@ -380,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** —— 那会静默开一个