dsh-remote-agent 0.9.1 → 0.9.2

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

@@ -305,14 +305,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 })

package/package.json

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

package/scripts/check-doc-drift.mjs

@@ -929,37 +929,55 @@ check('65', 'eslint 严格档：lint script + 配置文件 + CI job 三件套齐
     'lib/env-check.js（可达性/inject/roots/role + fix + 不代下载边界）')
 }
 
-/* ── 79~80. 开箱即用（2026-10-17）──
+/* ── 79~80. 开箱即用（2026-10-17，2026-10-18 修订）──
  *
  * 产品标准：用户装完就该能用，不该读文档、改 YAML、猜字段。
  *
- * 此前三道门槛：
- *   1. `role` 默认 '' → 两台机器都要操作一次
- *   2. `webserver` 没绑 0.0.0.0 → 副机永远连不上（且完全静默）
- *   3. 副机表单 4 个字段 → 小白不知道节点 ID / 工作区填什么
- *
  * 核心设计：`role` 默认 **auto**，按 `hubUrl` 推断。
  *   · 默认 hub → 副机装完以 hub 身份启动，注册无鉴权端点（**攻击面**）
  *   · 默认 ''  → 两台都要操作，不是开箱即用
  *   · 默认 auto → 主机零操作、副机贴完配对码零操作，且不给副机开错端点
+ *
+ * ⚠ **2026-10-18 事故修订**：79 号断言原来**要求**包内 patch 绑
+ * `host: '0.0.0.0'` —— 那正是导致 **DSH 启动崩溃**的写法。新版
+ * `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 ...
+ *
+ * 后果：webserver（required）激活失败 → webServer 服务缺失 → 至少 6 个插件
+ * 排队等它 → host 启动失败（实测 10 份 crash 日志）。
+ *
+ * 所以断言方向**反过来**：现在要求包内 patch **不碰** webserver 的任何字段，
+ * 且所有提示文案都不得建议 0.0.0.0。
  */
 {
   const indexSrc = read('lib/index.js')
   const patchSrc = read('cordis.patch.yml')
   const clientSrc3 = read('lib/client.js')
   const setupSrc = read('lib/setup-routes.js')
-
-  check('79', '开箱即用：role 默认 auto + 包内 patch 绑 0.0.0.0:19387',
+  const envSrc = read('lib/env-check.js')
+  const hubSrc = read('lib/hub/index.js')
+
+  // ⚠ 只扫**非注释行**：注释里必须保留那次事故的原文（含 `0.0.0.0` 与
+  // `- id: webserver` 示例），那是给后来者的警示 —— 不该被断言判违规。
+  // 这一点和 L3 断言踩过的坑同源（扫全文会命中"正确留档的注释"）。
+  const patchCode = patchSrc
+    .split('\n')
+    .filter((l) => !/^\s*#/.test(l))
+    .join('\n')
+
+  check('79', '开箱即用：role 默认 auto；且包内 patch **不得**绑 0.0.0.0（会让 DSH 崩溃）',
     /\.default\('auto'\)/.test(indexSrc)
     && /ROLE\.AUTO/.test(indexSrc)
     && /config\.hubUrl/.test(indexSrc)
-    // 包内 patch 必须 override webserver（否则副机连不上）
-    && /^- id: webserver$/m.test(patchSrc)
-    && /host:\s*'0\.0\.0\.0'/.test(patchSrc)
-    && /port:\s*19387/.test(patchSrc)
-    // 必须披露安全影响
-    && /暴露/.test(patchSrc),
-    'lib/index.js（auto 推断）+ cordis.patch.yml（webserver 0.0.0.0:19387 + 安全披露）')
+    // ⚠ 关键：包内 patch 的**生效行**不得 override webserver 的 host
+    && !/^- id: webserver$/m.test(patchCode)
+    && !/host:\s*'0\.0\.0\.0'/.test(patchCode)
+    // 必须把这个坑写进注释（防止后来者又"帮用户改好"）
+    && /启动崩溃/.test(patchSrc),
+    'lib/index.js（auto 推断）+ cordis.patch.yml（生效行不碰 webserver + 事故留档）')
 
   check('80', '开箱即用：副机表单简化 + 工作区自动创建 + 首次自动体检',
     // 工作区预填
@@ -972,6 +990,19 @@ check('65', 'eslint 严格档：lint script + 配置文件 + CI job 三件套齐
     && /mkdirSync\(r, \{ recursive: true \}\)/.test(setupSrc)
     && /warnings: applyWarnings/.test(setupSrc),
     'lib/client.js（预填/折叠/自动体检）+ lib/setup-routes.js（自动建目录）')
+
+  // ── 79b：**所有面向用户的修法文案**都不得建议 0.0.0.0 ──────────────
+  //
+  // 这是本次事故最有价值的一条守卫：代码自己不能犯那个错，提示文案也不能。
+  // 检查的是字符串字面量（`host: '0.0.0.0'` 这种形态），不是注释里的说明。
+  check('79b', '所有修法文案都不得建议 host 0.0.0.0（会让 DSH 启动崩溃）',
+    !/host:\s*'0\.0\.0\.0'/.test(clientSrc3)
+    && !/host:\s*'0\.0\.0\.0'/.test(envSrc)
+    && !/加 host:\s*'0\.0\.0\.0'/.test(hubSrc)
+    // 但要**明确警告不能用**它（否则用户可能自己想到这个"标准做法"）
+    && /不能用 0\.0\.0\.0/.test(envSrc)
+    && /不能用 0\.0\.0\.0/.test(clientSrc3),
+    'lib/client.js + lib/env-check.js + lib/hub/index.js（修法不含 0.0.0.0，且有明确警告）')
 }
 
 /* ── 81~82. 工作区 SMB 共享（2026-10-17）──

package/scripts/diag-worker.ps1

@@ -0,0 +1,148 @@
+# dsh-remote-agent worker diagnostic
+#
+# Read-only: changes nothing. Paste into PowerShell on the WORKER machine:
+#     powershell -ExecutionPolicy Bypass -File .\diag-worker.ps1
+
+$ErrorActionPreference = 'SilentlyContinue'
+$profiles = Join-Path $env:USERPROFILE '.dsh\profiles'
+
+function Line { param($t) Write-Host $t }
+
+Write-Host ''
+Write-Host '=========================================='
+Write-Host ' dsh-remote-agent WORKER DIAGNOSTIC'
+Write-Host '=========================================='
+Write-Host ''
+
+# ---- 1. profile dirs ----
+Write-Host '[1] DSH profile directories'
+if (Test-Path $profiles) {
+    Get-ChildItem $profiles -Directory | ForEach-Object {
+        $patch = Join-Path $_.FullName 'cordis.patch.yml'
+        if (Test-Path $patch) {
+            $f = Get-Item $patch
+            Line ("    {0}  patch={1}B  mtime={2}" -f $_.Name, $f.Length, $f.LastWriteTime.ToString('MM-dd HH:mm:ss'))
+        } else {
+            Line ("    {0}  (no cordis.patch.yml)" -f $_.Name)
+        }
+    }
+    if ($env:DSH_PROFILE) {
+        Line ("    env DSH_PROFILE = " + $env:DSH_PROFILE)
+    } else {
+        Line '    env DSH_PROFILE = (not set -> code defaults to "desktop")'
+    }
+} else {
+    Line '    ERROR: no profile directory'
+}
+Write-Host ''
+
+# ---- 2. remote-agent config per profile ----
+Write-Host '[2] remote-agent config in each profile'
+if (Test-Path $profiles) {
+    Get-ChildItem $profiles -Directory | ForEach-Object {
+        $patch = Join-Path $_.FullName 'cordis.patch.yml'
+        if (-not (Test-Path $patch)) { return }
+        $c = Get-Content $patch -Raw
+        if ($c -notmatch 'remote-agent') { return }
+
+        $roleM   = [regex]::Match($c, '(?m)^\s*role:\s*(\S+)')
+        $injectM = [regex]::Match($c, '(?m)^\s*inject:\s*(.+)$')
+        $hubM    = [regex]::Match($c, '(?m)^\s*hubUrl:\s*(\S+)')
+        $wsM     = [regex]::Match($c, '(?ms)- id:\s*webserver.*?host:\s*(\S+)')
+        $tokM    = [regex]::Match($c, '(?m)^\s*nodeToken:\s*(\S+)')
+
+        Line ('  --- ' + $_.Name + ' ---')
+        if ($roleM.Success)   { Line ('      role      = ' + $roleM.Groups[1].Value) }   else { Line '      role      = (NOT SET -> package default)' }
+        if ($injectM.Success) { Line ('      inject    = ' + $injectM.Groups[1].Value.Trim()) } else { Line '      inject    = (not set)' }
+        if ($hubM.Success)    { Line ('      hubUrl    = ' + $hubM.Groups[1].Value) }    else { Line '      hubUrl    = (not set)' }
+        if ($wsM.Success)     { Line ('      webserver = host=' + $wsM.Groups[1].Value) } else { Line '      webserver = (no webserver section)' }
+        if ($tokM.Success)    { Line '      nodeToken = (set)' } else { Line '      nodeToken = (not set)' }
+    }
+} else {
+    Line '    (skipped)'
+}
+Write-Host ''
+
+# ---- 3. installed plugin version ----
+Write-Host '[3] installed dsh-remote-agent version'
+$found = $false
+if (Test-Path $profiles) {
+    Get-ChildItem $profiles -Directory | ForEach-Object {
+        $nm = Join-Path $_.FullName 'node_modules\dsh-remote-agent'
+        $pj = Join-Path $nm 'package.json'
+        if (Test-Path $pj) {
+            $script:found = $true
+            $v = (Get-Content $pj -Raw | ConvertFrom-Json).version
+            $hasEnvCheck = Test-Path (Join-Path $nm 'lib\env-check.js')
+            $hasShare    = Test-Path (Join-Path $nm 'lib\node\share-service.js')
+            $pkgPatch    = Join-Path $nm 'cordis.patch.yml'
+            $pkgRole = ''
+            $hasWs = $false
+            if (Test-Path $pkgPatch) {
+                $pc = Get-Content $pkgPatch -Raw
+                $m = [regex]::Match($pc, '(?m)^\s*role:\s*(\S+)')
+                if ($m.Success) { $pkgRole = $m.Groups[1].Value }
+                $hasWs = $pc -match '(?m)^- id:\s*webserver'
+            }
+            Line ('  ' + $_.Name + ': version ' + $v)
+            Line ('    has lib/env-check.js (0.9+)     : ' + $hasEnvCheck)
+            Line ('    has lib/node/share-service.js   : ' + $hasShare)
+            if ($pkgRole -ne '') { Line ('    package default role            : ' + $pkgRole) } else { Line '    package default role            : (not found)' }
+            Line ('    package has webserver binding   : ' + $hasWs)
+            if (-not $hasEnvCheck) {
+                Line '    WARNING: this is pre-0.9, no "works out of the box"'
+            }
+        }
+    }
+}
+if (-not $script:found) {
+    Line '  ERROR: dsh-remote-agent not found under any profile'
+}
+Write-Host ''
+
+# ---- 4. panel endpoints ----
+Write-Host '[4] panel endpoint probe (is the plugin loaded at all?)'
+$ports = @()
+$dshPids = (Get-Process 'DeepSeek Harness').Id
+if ($dshPids) {
+    $ports += (Get-NetTCPConnection -State Listen | Where-Object { $dshPids -contains $_.OwningProcess } | ForEach-Object { $_.LocalPort })
+}
+$ports += 19387
+$ports = $ports | Sort-Object -Unique
+foreach ($port in $ports) {
+    foreach ($path in @('/api/remote-agent/setup/state', '/api/remote-agent/status')) {
+        $url = 'http://127.0.0.1:' + $port + $path
+        try {
+            $r = Invoke-WebRequest $url -UseBasicParsing -TimeoutSec 3
+            $body = $r.Content
+            if ($body.Length -gt 240) { $body = $body.Substring(0, 240) + '...' }
+            Line ('    [' + $port + '] ' + $path + ' -> HTTP ' + $r.StatusCode)
+            Line ('           ' + $body)
+        } catch {
+            $code = $_.Exception.Response.StatusCode.value__
+            if ($code) {
+                Line ('    [' + $port + '] ' + $path + ' -> HTTP ' + $code)
+            } else {
+                Line ('    [' + $port + '] ' + $path + ' -> no listener')
+            }
+        }
+    }
+}
+Write-Host ''
+
+# ---- 5. recent backups ----
+Write-Host '[5] recent config backups (was the file rewritten?)'
+if (Test-Path $profiles) {
+    Get-ChildItem $profiles -Recurse -File -Filter 'cordis.patch.yml*' |
+        Sort-Object LastWriteTime -Descending |
+        Select-Object -First 8 |
+        ForEach-Object {
+            Line ('    ' + $_.LastWriteTime.ToString('MM-dd HH:mm:ss') + '  ' + $_.Length + 'B  ' + $_.Name)
+        }
+}
+Write-Host ''
+
+Write-Host '=========================================='
+Write-Host ' END. Paste the whole output back.'
+Write-Host '=========================================='
+Write-Host ''