dsh-remote-agent 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -9,6 +9,154 @@
 
 ---
 
+## [0.9.4] - 2026-10-20
+
+> **0.9.3 审查的 19 项全部修完。** 0.9.3 把架构换对了（插件自己开 19387），
+> 但落地时几乎每一项都只改了"多条路径中的一条" —— 每个新机制都带着一个
+> 旧假设。本版逐条补齐。
+>
+> **0.9.3 有两个 Critical，请直接升级到 0.9.4**：
+> 配对码端口取的是 DSH webserver 的端口（复制的码 100% 连不上）；
+> `nodeToken` 为空时独立监听成了 tailnet 内的无鉴权接入点。
+>
+> 架构（独立监听 / 配置分层 / 绑址优先链）见 0.9.3 条目，本版不改它。
+
+### 本版修掉的 19 个问题（0.9.3 审查）
+
+**Critical**
+
+- **C1 配对码端口是错的** —— 前端把浏览器地址栏端口（DSH webserver 的
+  58626 之类）拼进配对码，而节点端点在 19387 → **复制的码 100% 连不上**。
+  现在 `/pair-info` 从 `listenRuntime` 取**实际绑定端口**，响应带 `portSource`
+  （`listen-server` / `fallback`），每个候选地址标 `usable`，可用项排最前。
+- **C2 配对码的地址顺序与绑定顺序相反** —— `detectLanIps()` 自己实现了一套
+  分类（私网优先），而 `resolveListenHost()` 是 Tailscale 优先 → 首选地址
+  根本不是监听地址。现在 `detectLanIps()` 复用 `listCandidateAddresses()`，
+  判据只有一份。
+
+**High**
+
+- **H1 `nodeToken` 为空时端点暴露到网络** —— 现在 token 为空且没显式指定可达
+  `listenHost` 时**强制绑 `127.0.0.1`**，面板给黄色提示引导去「生成口令」。
+- **H2 setup 表单只管 6 个字段，写盘却整块重写** —— 用户在 YAML 里手写的
+  `uiPullRoot` / `listenHost` 等被静默抹掉。新增 `extractPreservedConfig`
+  文本级切分，**只覆盖表单管辖的键**（`role/nodeId/transportMode/hubUrl/
+  relayUrl/roots`），其余原样保留。
+- **H3 面板没有生成口令的入口** —— token 为空时只能看到"绑回环"却无路可修。
+  新增 `POST /setup/rotate-token`（**仅接受回环请求**），面板加「生成口令」
+  按钮（带二次确认），明文只回一次。
+- **H4 CI 连红两次还发了 npm** —— `test/doc-drift-selfcheck.test.js` 的手工
+  复制清单漏了 `lib/listen-server.js`，副本里 `read()` 抛 ENOENT → **20 个
+  自检用例全挂**（不是单条断言失败）。这是同一规矩**第六次**被踩。
+  结构性修复：改成**自动扫 `lib/*.js` 全量复制**，手工清单只管目录与非 js 目标。
+- **H5 架构换了，诊断层没换** —— reachability 快照、`/env-check`、面板横幅、
+  README 全停留在 `webserver` 语义 → **面板报假红**（独立监听 19387 明明在跑）
+  并教用户做无效操作（改 webserver host，改了也会被冲掉）。现在：
+  `reachability` 变**两层结构 + getter**（运行时绑定后动态求值），
+  新增 `listener` 四态（未就绪 / 就绪 / 已关闭 / 失败），横幅三态
+  （正常不显示 / 绑回环黄条 / 启动失败红条），README 安装段重写。
+
+**Medium**
+
+- **M1 `writeInstanceConfig(values)` 没传 `config`** —— 写默认 stateDir，而读
+  的一方按 `config.stateDir` 找，两边对不上。补上第二个参数。
+- **M2 `listenHost` / `listenPort` / `relay` 不在持久化白名单** —— 写进
+  instance.json 会被静默丢弃。`PERSISTED_KEYS` 补齐，`relay` 按对象白名单
+  （`url` / `token`）处理；schema 也补上 `listenHost` / `listenPort` 声明
+  （此前靠 schemastery passthrough 生效，**无表单、无校验**）。
+- **M3 instance.json 静默覆盖 patch 值** —— 现在 `mergeInstanceConfig` 返回
+  `shadowed: string[]`，`apply()` 里 `log('info', …)` 明示谁覆盖了谁；
+  `--doctor` 也会报告"instance.json 覆盖了 patch 的：…"。
+- **M4 配对码端口取错** —— 用的是浏览器地址栏的端口（DSH 的 webserver 端口，
+  常见 58626），而副机该拨的是 19387。现在从 `listenRuntime` 取**实际绑定端口**，
+  响应带 `portSource`，并给每个候选地址标 `usable`（只有与本机绑定地址一致的
+  才算可用，可用项排最前）。
+- **M5 CLI 写盘路径不写 instance.json** —— 向导/`--apply` 写完 patch 后，
+  重启 DSH 又会被重写。`offerWrite` / `applyWrite` 增加 `persist` 参数，
+  成功后同步写独立配置。
+
+**Low / Info**
+
+- **L1 `server.on('error')` 在 listen 成功后无声吞错** —— 加 `settled` 闸门：
+  首次 reject，之后转 `log('error', 'listen server error (runtime)')`。
+- **L2 回环判据三份实现**（listen-server / env-check / 面板各写一份）——
+  统一导出 `isLoopbackHost()`，其余全部 import。
+- **L3 `explicitPort` 判断看的是归一化后的值** —— 改成看**原始 config 是否
+  有该键**（否则"没填"和"填了默认值"无法区分）。
+- **L6 候选地址顺序随网卡枚举变化** —— `listCandidateAddresses()` 按
+  `score`（Tailscale=0 / 私网=1 / 其它=2）+ 接口名 + 地址稳定排序，
+  避免同一台机器两次启动绑到不同 IP。
+
+### 断言与门禁
+
+- **85 改向**：要求 CLI `--doctor` 用 `listen-server` 的回环判据，
+  并**负向守卫**——不得再从 patch 里找 `- id: webserver` 判可达性
+  （扫剥注释后的代码，注释里的历史留档不算违规）。
+- **79b 加固**：三处面向用户的文案必须同时满足"不建议 `0.0.0.0`"与
+  "包含不能用 `0.0.0.0` 的警告"。
+- 自检不再依赖 import 的**排版**（`writePatchBlock` 的断言改为匹配符号
+  而非单行字面量）—— 断言的是依赖关系，不是格式。
+
+```
+packaging   4 项
+doc-drift   123/123
+diag:inject 11 项
+tests       982（980 pass / 0 fail / 2 skip）
+lint        干净（eslint 严格档，含 bin/ 与 test/）
+```
+
+### 升级须知
+
+- **不用再给 `webserver` 填 host**。之前填过的可以删掉（留着也无害，DSH 会
+  自己重写掉）。
+- 想固定绑哪个地址：`listenHost: '100.x.x.x'`；端口冲突就换 `listenPort`。
+- 防火墙要放行的是 **`listenPort`（默认 19387）**，不再是 DSH 的 Web 端口。
+- **面板里点过一次「生成口令」的，副机要用新口令重新配对**（旧口令已换掉）。
+
+## [0.9.3] - 2026-10-18
+
+> **架构级重做：插件自己开端口，副机拨入不再依赖 DSH 的 `webserver`。**
+>
+> ⚠ **0.9.2 那段"去 patch 里给 `webserver` 填一个具体 host"的做法从本版起
+> 作废** —— 不用填了，填了也会被 DSH 每次启动重写掉。
+>
+> 🔴 **本版有两个 Critical，已被 0.9.4 修复，请不要停留在本版**：
+> 面板生成的配对码用了 DSH webserver 的端口（粘了连不上）；
+> `nodeToken` 为空时独立监听变成了 tailnet 内的无鉴权接入点。
+> 另外本版发布时 **CI 是红的**（win + ubuntu 全红、本地实测 20 fail）。
+
+### 为什么必须换架构（三个死结，均实证）
+
+| 死结 | 现象 |
+|---|---|
+| **patch 被重写** | DSH 每次启动都重写 `cordis.patch.yml`，实测 3962B / 15 条 → **661B / 3 条**，写进去的 `webserver` 段被删光 |
+| **webServer 无 rebind** | `webServer` 服务激活即 `listen`，没有改绑方法，插件拿不到控制权 |
+| **硬拒通配地址** | 新版 `dsh-host-webserver` 在 schema 阶段就拒绝 `0.0.0.0`，绑了就 **DSH 启动崩溃**（已产生 10 份 crash 日志） |
+
+结论：**副机端点不能再挂在 `ctx.webServer` 上。**
+
+### 新方案
+
+- **`lib/listen-server.js`** —— 用 `node:http` 自己开一个只服务节点端点的小
+  server：`GET <healthPath>` 回 200 JSON，`Upgrade: websocket` 复用 `ws.js`
+  的 `acceptUpgrade`，**路径精确匹配**，其它一律 404；关闭时追踪并断开所有连接。
+- **绑址优先链**：`listenHost` > Tailscale IP（`100.64.0.0/10`）> RFC1918 私网
+  > 任意非回环 > `127.0.0.1`；**拒绝** `0.0.0.0` / `::` / `[::]`。
+  默认端口 **19387**，`listenPort: 0` = 关闭独立监听。
+- **`lib/instance-config.js`** —— 配置分层：patch 只负责"让 loader 加载插件"，
+  真配置存 `<stateDir>/instance.json`（**0600 + 原子写 + 字段白名单**）。
+  `mergeInstanceConfig` 合并时**独立配置优先**，`apply()` 里重新归一化。
+- **安全边界**：token 校验仍是同一份逻辑，独立监听不降低门槛。
+  （`nodeToken` 为空的处理是本版**没做到位**的地方，见 0.9.4 的 H1。）
+
+```
+packaging   4 项
+doc-drift   121/121
+diag:inject 11 项
+tests       975（953 pass / 20 fail / 2 skip）   ← 发布时实际是红的
+lint        干净
+```
+
 ## [0.9.2] - 2026-10-18
 
 > **紧急修复：0.9.0/0.9.1 会让新版 DSH 启动崩溃。**

package/CONTRIBUTING.md

@@ -351,7 +351,9 @@ Node 24 下会把目录当模块入口，必然失败。用 `npm test`（内部
 3. **角色**（`config.role`）与**传输方式**（`transportMode`）
 4. **现象 + 复现步骤**
 5. **日志**：
-   - 主机侧：面板「日志尾部」区，或 `/api/remote-agent/healthz`
+   - 主机侧：面板「日志尾部」区，或 `GET /api/remote-agent/healthz`
+     带 `x-dsh-token: <nodeToken>` 头（匿名只回 `{ "ok": true }`，
+     拿不到节点/任务计数 —— 0.9.3 起的分级策略）
    - 副机侧：`%TEMP%\dsh-remote-agent-diag.log`（若有）
    - 启动日志：`<DSH_HOME>/logs/` 与 `%APPDATA%\@deepseek-ai\dsh-desktop\logs`
 

package/KNOWN-ISSUES.md

@@ -572,6 +572,8 @@ $env:DSH_REMOTE_PWSH = 'C:\nope\pwsh.exe'
 2. **registry 上下线实时性**：worker 在线时 `healthz` 报 `online:2`，
    进程退出后数秒内回落到 `online:1` —— 真实 webServer 路由下的
    在线状态检测是活的。
+   （0.9.3 起计数只回给带正确 `x-dsh-token` 的请求；匿名只回 `{ ok: true }`，
+   见 CHANGELOG 0.9.3 的 L4 条。）
 3. **UI 围栏确认（安全结论，非缺陷）**：hub 的 webserver 除 `/healthz`
    外**整台 401**（`/`、`/index.html`、`/ui/config`、`/ui/overview` 全中）
    —— 没有桌面会话的请求一律被 `requestRejection` 拦掉。这意味着：

package/README.en.md

@@ -37,7 +37,7 @@ explicitly pull them.
 | **Platforms** | Windows (fully verified) · Linux / macOS (CI covered) |
 | **Dependencies** | **Zero external npm dependencies** —— `node:` built-ins only |
 | **Node** | `^22.19.0 \|\| >=24.0.0` |
-| **Tests** | 938 (937 pass / 1 skip) · 118 doc-drift assertions · eslint strict |
+| **Tests** | 982 (980 pass / 2 skip) · 123 doc-drift assertions · eslint strict |
 
 **Web panel**（sidebar → "远程同事" / Remote co-worker）：node list with CPU /
 memory badges, task dispatch, task states, result summaries, workspace changes,
@@ -47,13 +47,15 @@ change diffs (unified diffs of text-file edits), final artifacts, log tail,
 > **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.
+> **Workers connect to the plugin's own port — no DSH config to touch.**
+> Since 0.9.3 the plugin runs its own listener (default **19387**) that workers
+> dial directly; it does **not** go through `webserver`, so you never edit a
+> `host` in `cordis.patch.yml`.
 >
-> ⚠ **Never use `0.0.0.0`**: newer DSH rejects wildcard addresses and will
-> **fail to start**. See *Install* below.
+> The bind address is chosen automatically: `listenHost` (if set) > Tailscale
+> IP > LAN IP > loopback. Set `listenHost: '100.x.x.x'` to pin it.
+> **`0.0.0.0` is always rejected** (newer DSH refuses wildcard addresses —
+> binding one crashes DSH on startup). See *Install* below.
 
 <p align="center">
   <img src="docs/screenshots/panel-main.png" width="720" alt="Web panel: nodes, dispatch form, task list">
@@ -244,6 +246,23 @@ in-package patch inserts it automatically):
     role: hub
 ```
 
+**No `webserver` tuning needed.** The plugin listens on its own port (default
+`19387`) and workers dial that, so the DSH web server's bind address is
+irrelevant. Optional overrides:
+
+```yaml
+  config:
+    role: hub
+    listenHost: '100.x.x.x'   # optional: blank = auto (Tailscale > LAN > loopback)
+    listenPort: 19387         # optional: default 19387; 0 = disable the listener
+```
+
+> **Security policy: no token, no network exposure.** With an empty
+> `nodeToken` the listener binds `127.0.0.1` only (same-machine `both` mode
+> still works) and the panel shows a **yellow** banner pointing at
+> “生成口令”. Generate one and restart DSH to get the reachable address back.
+> To override deliberately, set a concrete non-loopback `listenHost`.
+
 ### Worker
 
 **Same package, different config** —— the key point is that **`inject: []` is

package/README.md

@@ -30,12 +30,12 @@
 
 | | |
 |---|---|
-| **状态** | 0.9.0 —— 主机 + 副机端到端可用；`exec` 与 `agent` 双链路均已在两台真机上验证通过；CI 覆盖 Windows / macOS / Linux |
+| **状态** | 0.9.4 —— 主机 + 副机端到端可用；`exec` 与 `agent` 双链路均已在两台真机上验证通过；CI 覆盖 Windows / macOS / Linux |
 | **DSH** | 桌面版 / CLI，0.2.0-rc.2 验证 |
 | **平台** | Windows（全量验证）· Linux / macOS（CI 覆盖）|
 | **依赖** | **零外部 npm 依赖** —— 只用 `node:` 内置模块 |
 | **Node** | `^22.19.0 \|\| >=24.0.0` |
-| **测试** | 938 项（937 pass / 1 skip）· 118 条文档漂移断言 · eslint 严格档 |
+| **测试** | 982 项（980 pass / 2 skip）· 123 条文档漂移断言 · eslint 严格档 |
 
 **Web 面板**（侧栏「远程同事」）：节点列表（含 CPU/内存徽章）、派发任务、
 任务状态、结果摘要、工作区变更、成品清单、日志尾巴、**环境体检**、
@@ -44,11 +44,13 @@
 > **开箱即用**：装完重启 DSH 就能用。包内 patch 默认 `role: auto`（没配
 > `hubUrl` 就是主机），自动生效。
 >
-> **副机要能连上，主机的 `webserver` 必须绑一个具体的本机 IP**（DSH 默认只绑
-> `127.0.0.1`，那样副机永远连不上）。这一步需要你填一次 —— 打开面板时
-> 「环境体检」会检查并告诉你该填什么。
+> **副机连的是插件自己的端口，不用改 DSH 的任何配置。** 0.9.3 起本插件自己
+> 开一个独立监听（默认 **19387**），副机直接拨这个端口 —— **不再依赖
+> `webserver`**，也就不用去 `cordis.patch.yml` 里填 host。
 >
-> ⚠ **不能用 `0.0.0.0`**：新版 DSH 会硬拒绝通配地址，导致 DSH **启动崩溃**。
+> 绑哪个地址是自动选的：`listenHost`（如果你填了）> Tailscale IP >
+> 局域网 IP > 回环。想指定就配 `listenHost: '100.x.x.x'`；
+> **`0.0.0.0` 一律拒绝**（新版 DSH 硬拒通配地址，绑了会让 DSH 启动崩溃）。
 > 详见下方「安装」。
 
 <p align="center">
@@ -221,24 +223,30 @@ npm install -g dsh-remote-agent
 - 包内 patch 默认 `role: auto`。**没配 `hubUrl` 就是主机**，自动生效。
 - 打开 Web 面板「远程同事」，点「副机接入」生成配对码，发给副机。
 
-**唯一需要你填一次的是 `webserver` 的 host** —— 副机要能连上，主机必须绑一个
-**具体的本机 IP**（DSH 默认只绑 `127.0.0.1`，那样副机永远连不上，而且主机侧
-毫无异常）。在 profile 的 `cordis.patch.yml` 里：
+**不需要改 DSH 的 `webserver`。** 0.9.3 起插件自己监听一个端口（默认 19387），
+副机拨的是它，不是 DSH 的 Web 端口。历史上那套"去 patch 里给 webserver 填一个
+具体 host"的做法**已经作废** —— 它还有个副作用：DSH 每次启动都会重写 patch，
+填进去的 `webserver` 段会被删掉（实测 15 条配置剩 3 条）。
+
+**想指定绑哪个地址**（多数情况不用，自动选的就是对的）：
 
 ```yaml
-- id: webserver
+- id: remote-agent
   config:
-    host: '100.x.x.x'    # ← 换成你自己的地址
-    port: 19387
+    listenHost: '100.x.x.x'   # 可选：留空=自动（Tailscale > 局域网 > 回环）
+    listenPort: 19387         # 可选：默认 19387；填 0 = 关闭独立监听
 ```
 
+**自动选的顺序**是 `listenHost`（填了就用它）→ Tailscale IP（`100.64.0.0/10`）
+→ 局域网私网 IP → 任意非回环 → `127.0.0.1`。
+
 **怎么查自己的地址**：
 
 - 跨网（推荐）：`tailscale ip -4` —— Tailscale IP 固定不变、跨网可达
 - 同一局域网：`ipconfig` 看 WLAN/以太网那块网卡的 IPv4
 
-> ⚠ **绝对不能写 `0.0.0.0`**。新版 `@deepseek-ai/dsh-host-webserver` 在 schema
-> 校验阶段就会硬拒绝通配地址：
+> ⚠ **`listenHost` 不能写 `0.0.0.0`**（`::` 也不行）。新版
+> `@deepseek-ai/dsh-host-webserver` 在 schema 校验阶段就硬拒绝通配地址：
 >
 > ```
 > host "0.0.0.0" is an unspecified (wildcard) address, which is not supported:
@@ -246,11 +254,16 @@ npm install -g dsh-remote-agent
 > bind one concrete IPv4 or IPv6 address of a local interface instead
 > ```
 >
-> 后果是 **DSH 启动崩溃**（`webserver` 是 required 插件，它挂了 `webServer`
-> 服务就缺失，至少 6 个插件排队等它，包括本插件）。
+> 本插件自己开端口，同样**主动拒绝**通配地址：填了会退回自动选择，而不是
+> 把端点暴露到所有网卡。
 >
-> 面板的「环境体检」会自动检测这一项，绑错了会明确告诉你当前绑在哪、
-> 该改成什么 —— 面板加载时也会自动体检一次。
+> 面板的「环境体检」会检查独立监听有没有起来、绑在哪、副机能不能拨进来；
+> 连不上时按提示修（每条 ✗ 都带具体怎么做）。
+
+> **安全策略：`nodeToken` 为空时不暴露到网络。** 没有入网口令的开放在公网/
+> 局域网里等于把 RCE 送人。这种情况下插件只绑 `127.0.0.1`（本机 both 模式
+> 仍可用），面板会显示一条**黄色**提示告诉你去点「生成口令」。生成后重启
+> DSH 即恢复可达地址 —— 想强行对外就显式填一个非回环的 `listenHost`。
 
 ### 副机（worker）—— 贴个配对码就行
 

package/bin/dsh-remote-setup.js

@@ -36,7 +36,9 @@ import { encodePairCode, decodePairCode } from '../lib/pairing.js'
 // loopback 诊断** —— 而它正是本版本最重要的那条。现在两段都跑、结果合并。
 // resolveRole 保证 auto 被推断成实际角色（与运行时同一份实现）。
 import { resolveRole } from '../lib/index.js'
-import { envChecks, isLoopbackOrigin } from '../lib/env-check.js'
+import { envChecks } from '../lib/env-check.js'
+import { resolveListenHost, isLoopbackHost } from '../lib/listen-server.js'
+import { readInstanceConfig, writeInstanceConfig } from '../lib/instance-config.js'
 import { IDENTITY_FILE_NAME, readHubIdentity } from '../lib/identity.js'
 
 const DIM = '\x1b[2m'
@@ -114,8 +116,12 @@ function printYaml(name, yaml, outFile) {
 /**
  * 询问并把 YAML 写进本机 DSH 配置（备份 → 托管块合并 → 校验，失败自动回滚）。
  * 写盘是零终端小白的"最后一公里"：不用自己找配置文件、开编辑器、粘 YAML。
+ *
+ * @param {object} [persist] 同时写入 `<stateDir>/instance.json` 的字段（2026-10-20，M5）。
+ *   patch 那层会被 DSH 每次启动重写冲掉，instance.json 才是"重启后配置还在"的保障。
+ *   面板配的走这条，CLI 配的也必须走 —— 否则同一台机器换个配置方式行为就不同。
  */
-async function offerWrite(rl, values, yaml, roleLabel) {
+async function offerWrite(rl, values, yaml, roleLabel, persist = null) {
   if (values['no-write']) return false
   const profile = String(values.profile ?? '').trim() || 'desktop'
   const file = patchFilePath(profile)
@@ -129,15 +135,29 @@ async function offerWrite(rl, values, yaml, roleLabel) {
     validate: (v) => (['y', 'yes', 'n', 'no', '1', '0'].includes(v.toLowerCase()) || '输 Y 或 N'),
   })
   if (!['y', 'yes', '1'].includes(yes.toLowerCase())) return false
-  return applyWrite({ file, blockYaml: yaml, force: values.force === true })
+  return applyWrite({ file, blockYaml: yaml, force: values.force === true, persist })
 }
 
 /** 非交互写盘执行 + 结果播报。返回 true = 成功。 */
-function applyWrite({ file, blockYaml, force }) {
+function applyWrite({ file, blockYaml, force, persist = null }) {
   const r = writePatchBlock({ file, blockYaml, force })
   if (r.ok) {
     say(`  ✓ 已${r.mode === 'replaced' ? '更新（原托管块替换）' : '写入（追加托管块）'} ${r.file}`)
     say(`    （原文件已备份：${r.backup}）`)
+    // 独立配置这一层（2026-10-20）：DSH 会重写 patch，只有这里存的能扛住
+    if (persist && typeof persist === 'object') {
+      try {
+        const prev = readInstanceConfig({}) ?? {}
+        const next = { ...prev }
+        for (const k of Object.keys(persist)) if (persist[k] === undefined) delete next[k]
+        Object.assign(next, persist)
+        const w = writeInstanceConfig(next, {})
+        if (w.ok) say(`  ✓ 已写入独立配置 ${w.file}（DSH 重写 patch 也不会丢）`)
+        else hint(`  ⚠ 独立配置写入失败（${w.error}）—— 重启后角色配置可能被 DSH 冲掉`)
+      } catch (err) {
+        hint(`  ⚠ 独立配置写入异常（${String(err?.message ?? err)}）—— 不影响本次 patch 写入`)
+      }
+    }
     hint('  重启 DSH 后生效。')
   } else {
     say(`  ✗ ${r.error}`)
@@ -177,8 +197,37 @@ async function runDoctor(positionals) {
     pair: grab('pair'),
     roots,
     uiPullRoot: grab('uiPullRoot'),
+    // 独立监听（v0.9.3 起的主通道）。listenPort 必须是 number —— 0 有语义
+    // （= 关闭），所以不能用 `Number(x) || 19387` 那种写法把它吃掉。
+    listenHost: grab('listenHost'),
+    listenPort: (function () {
+      const v = grab('listenPort')
+      if (v === '') return 19387
+      const n = Number(v)
+      return Number.isFinite(n) && n >= 0 ? n : 19387
+    })(),
   }
 
+  // ⚠ 独立配置优先（v0.9.3 审查 M2/M3）：DSH 每次启动都会重写 patch，
+  // 真正生效的字段存在 `<stateDir>/instance.json` 里并**覆盖** patch 的值。
+  // 只读 patch 体检 = 报告一个已经不在生效的配置（比如用户在面板里改了
+  // listenPort，patch 里还是旧的 19387）。
+  //
+  // 先拍一张 patch 快照，合并之后再拿它比对 —— 否则"谁覆盖了谁"永远看不出
+  // （config 已被改写，比较恒等）。
+  const patchSnapshot = { ...config }
+  let instanceSrc = null
+  try {
+    const saved = readInstanceConfig({})
+    if (saved && typeof saved === 'object') {
+      for (const k of Object.keys(saved)) {
+        if (!(k in config)) continue
+        if (saved[k] !== undefined) config[k] = saved[k]
+      }
+      instanceSrc = saved
+    }
+  } catch { /* 读不到就当没有 */ }
+
   // 角色解析用**与运行时同一份实现**（唯一真相）：auto 在这里被推断成
   // 实际角色，这样 doctor 报告的 role 与 hub 实际行为一致。
   const resolvedRole = resolveRole(config) || ''
@@ -204,30 +253,60 @@ async function runDoctor(positionals) {
   //
   // 探测参数：CLI 能真探测的才传，拿不到的留 null（envChecks 会跳过该项，
   // 不会误报）。
-  //   · webserver host 从配置文件里读（静态可判 —— 正是 loopback 检查的关键）
+  //   · 独立监听：从 **生效配置**（instance.json 覆盖后）用与运行时同一份
+  //     `resolveListenHost` 算出来，再用本机 TCP 探活判断"插件是否真在听"
   //   · roots 存在性真查文件系统
+  //
+  // ⚠ **绝不能再从 patch 里读 `- id: webserver`**（v0.9.3 审查 H5 的 CLI 侧）：
+  // 0.9.3 起端点由插件自己的独立监听承载，webserver 的 host 与副机能否接入
+  // **毫无关系**。老代码读到 `host: 127.0.0.1` 就报"副机连不上，去改
+  // webserver"，把用户引向一个改了也会被 DSH 重写冲掉、且修不好的方向。
   try {
-    const wsHost = grab('host')
-    const wsPort = grab('port')
-    // 从配置里找 webserver 段（形如 `- id: webserver` 之后几行的 host/port）
-    const wsBlock = /- id:\s*webserver[\s\S]{0,400}?host:\s*['"]?([^'"\n]+)['"]?[\s\S]{0,120}?port:\s*(\d+)/.exec(raw)
-    const boundHost = wsBlock ? wsBlock[1].trim() : (wsHost || '')
-    const boundPort = wsBlock ? Number(wsBlock[2]) : (Number(wsPort) || 19387)
-    const loopback = isLoopbackOrigin(`http://${boundHost || '127.0.0.1'}:${boundPort}`)
+    const listenPort = config.listenPort
+    const tokenBlank = config.nodeToken === ''
+    const explicitNonLoop = config.listenHost !== '' && !isLoopbackHost(config.listenHost)
+    // 与 applyHub 同一条安全策略：token 为空且没显式指定可达地址 → 强制回环
+    const pick = listenPort === 0
+      ? { host: '', source: 'disabled' }
+      : (tokenBlank && !explicitNonLoop
+          ? { host: '127.0.0.1', source: 'loopback-no-token' }
+          : resolveListenHost({ listenHost: config.listenHost }))
+
+    // 本机 TCP 探活：能连上 = 插件此刻确实在听（比"配置看起来对"强得多）
+    let alive = null
+    if (pick.host !== '') {
+      const probe = await probeTcp(isLoopbackHost(pick.host) ? '127.0.0.1' : pick.host, listenPort)
+      if (probe.ok) alive = true
+      else if (probe.error === 'ECONNREFUSED') alive = false
+      // 其它错误（超时/EHOSTUNREACH）→ 无法判定，保持 null
+    }
+
+    const listener = {
+      // 连不上时**不要**断言"启动失败"：DSH 可能根本没在跑（CLI 常在停机时用）
+      ok: pick.host === '' ? false : alive,
+      disabled: pick.host === '' ? '配置里 listenPort: 0（显式关闭独立监听）' : '',
+      host: pick.host,
+      port: listenPort,
+      source: pick.source,
+      error: alive === false ? `本机 ${listenPort} 端口没有在听（DSH 未运行？或端口被占）` : '',
+    }
+
     const missingRoots = config.roots.filter((r) => {
       try { return !fs.existsSync(r) } catch { return true }
     })
     const env = envChecks({
       role: resolvedRole || 'hub',
       config,
-      reachability: boundHost === '' && !wsBlock
+      reachability: pick.host === ''
         ? null
         : {
-          bound: boundHost,
-          origin: `http://${boundHost || '127.0.0.1'}:${boundPort}`,
-          loopback: loopback === true,
+          bound: pick.host,
+          origin: `${pick.host}:${listenPort}`,
+          loopback: isLoopbackHost(pick.host),
+          via: 'listen-server',
           hint: '',
         },
+      listener,
       missingRoots,
     })
     // 合并：envChecks 的项追加到 CLI 结果后（格式一致：{ok, label, fix}）
@@ -239,6 +318,20 @@ async function runDoctor(positionals) {
         fix: it.fix,
       })
     }
+
+    // 独立配置来源提示：patch 与 instance.json 不一致时说明以谁为准
+    if (instanceSrc && typeof instanceSrc === 'object') {
+      const overridden = ['role', 'hubUrl', 'listenHost', 'listenPort']
+        .filter((k) => instanceSrc[k] !== undefined
+          && String(instanceSrc[k]) !== String(patchSnapshot[k] === undefined ? '' : patchSnapshot[k]))
+      checks.push({
+        ok: true,
+        label: overridden.length === 0
+          ? '独立配置 instance.json 已加载（与 patch 一致）'
+          : `独立配置 instance.json 覆盖了 patch 的：${overridden.join(' / ')}（DSH 重写 patch 也不会丢）`,
+        fix: '',
+      })
+    }
   } catch (err) {
     // envChecks 自身出错不能挡 CLI 体检（它只是补充）
     checks.push({ ok: true, label: `（运行时态检查不可用：${String(err?.message ?? err)}）`, fix: '' })