dsh-remote-agent 0.9.5 → 0.9.7

package/CHANGELOG.md

@@ -9,6 +9,167 @@
 
 ---
 
+## [0.9.7] - 2026-10-20
+
+> **0.9.6 的 CI 回归修复。** 0.9.6 在本地全绿，但 GitHub Actions 的
+> `ubuntu-latest / node 24.x` 上 E2E 握手全部超时。
+
+### 修复：X25519 私钥重建改用 DER，不再依赖 JWK 的 `x` 校验
+
+**现象**（CI run `39384173448`，只有 ubuntu/node24 失败）：
+
+    Error: timeout waiting for e2e session on test-worker
+    code: 'ERR_CRYPTO_INVALID_JWK'
+
+**根因**：`lib/e2e.js` 用 JWK 重建私钥：
+
+```js
+createPrivateKey({ key: { kty: 'OKP', crv: 'X25519', d: b64, x: '' }, format: 'jwk' })
+```
+
+本地 Node 24.18 接受 `x: ''`，但 CI 那个 Node 24 小版本**不接受**
+（空串不是合法 base64url；省略 `x` 同样被拒）。
+
+**这个 bug 为什么藏了这么久**：失败表现为
+`timeout waiting for e2e session` —— **真因（ERR_CRYPTO_INVALID_JWK）被
+完全掩盖**，看起来像时序抖动，而本地又复现不了。
+
+**修法**：直接用 DER 构造 —— X25519 私钥的 PKCS#8 就是
+固定 16 字节前缀 + 32 字节标量。这条路径**不经过 JWK 校验**，跨 Node
+小版本稳定。
+
+实测验证：DER 构造出的私钥导出的公钥 `x` 与原始 JWK 完全一致，
+DH 协商结果与正常生成的密钥对一致。
+
+**测试**：`test/e2e.test.js` 新增 2 条 ——
+双方派生会话密钥必须一致（E2E 握手的核心数学）、非法长度必须明确抛错。
+
+### 0.9.6 的五项体验提升（本版包含）
+
+- **④ 统一错误翻译层** —— errno + 17 个协议码 + HTTP + 文案特征，每条带"下一步"
+- **① 副机连接状态可见** —— 记录每次连接尝试，空态显示原因与修法
+- **② 一键复制修法** —— 体检项旁的「复制修法」按钮（只复制，不代改文件）
+- **③ 首次使用向导** —— 编号步骤 + 每步"应该看到什么"
+- **⑤ 任务进度摘要** —— 任务行直接显示"最近：调用工具 Write · 共 23 步"
+
+```
+packaging   4 项
+doc-drift   126/126
+diag:inject 11 项
+tests       1009（1007 pass / 0 fail / 2 skip）
+lint        干净
+```
+
+## [0.9.6] - 2026-10-20
+
+### 用户体验：五项提升（"出了问题不知道原因"的正面回应）
+
+用户实测反馈的核心痛点不是功能不够，而是**看不到系统在做什么**。
+下面五项都指向同一件事：**让每一步的状态可见、每个错误可行动**。
+
+#### ④ 统一错误翻译层（`lib/explain-error.js`）
+
+此前原始错误直接抛给用户：
+
+    connect ECONNREFUSED 100.86.48.54:19387
+    handshake timeout: no welcome/accepted within 15000ms
+    task t-xxx terminal: timeout after 40000ms
+    HTTP 401 {"error":"unauthorized"}
+
+项目里原本有一份 `friendlyConnectError`（`lib/setup.js`），但只覆盖 5 类
+网络错误、且没用到协议错误码。现在统一到一处，覆盖：
+
+- **errno**（ECONNREFUSED / ETIMEDOUT / EADDRINUSE / EADDRNOTAVAIL / …）
+- **协议错误码**（17 个，全部有专门翻译）
+- **HTTP 状态**（401/403/404/405/409/500/502/503/504）
+- **文案特征**（`timeout after Nms` → 换算成秒、`handshake timeout` → 版本差异）
+
+**每条都给"下一步做什么"**，并保留原始信息（`raw`）供排查。
+
+设计约束：**绝不抛**、**不猜**（拿不准的如实说"未知，请附原始错误"）。
+
+#### ① 副机连接状态可见
+
+**此前**：副机连不上时主机只显示「0 在线」，**没有任何原因**。
+用户为此排查了两天（重启回引导页、19387 不监听、SMB 密码…）。
+
+**现在**：注册表记录**每一次连接尝试**（成功/失败 + 原因 + 时间 + 远端地址，
+环形上限 50 条）。面板节点区空态渲染：
+
+    ✗ newland 连接失败                        2 分钟前
+      100.72.146.73:19387 连不上（超时）
+      → 检查：① 两台机器能否互 ping；② 主机防火墙；③ 是否同一局域网
+      原始：connect ETIMEDOUT
+
+并区分三种情形（**排查方向完全不同**）：
+
+- 有失败记录 → 显示原因与修法
+- 从没尝试过 → "副机还没开始连"
+- 连过但现在不在线 → "副机 DSH 可能没在跑"
+
+#### ② 一键复制修法
+
+体检项旁边加「复制修法」按钮。修法里常含可直接粘贴的 YAML/命令，
+让用户手抄是纯粹的摩擦。
+
+**只做复制，不做"一键修复"** —— 后者会改用户文件，风险 > 收益
+（我们刚因为改 DSH 文件出过事故）。
+
+#### ③ 首次使用向导
+
+配置完成后的"下一步"从一句话变成**编号步骤 + 每步"你应该看到什么"**：
+
+    1  重启 DSH          必须
+       关掉 DSH 窗口再打开。配置只在启动时读取。
+    2  生成配对码
+       重启后这个面板会出现「副机接入」按钮 —— 点它，复制那行 dshra1://
+    3  在副机上粘贴
+       副机也装本插件 → 打开面板 → 粘贴 → 保存 → 重启副机 DSH
+    4  等它连上
+       「在线节点」会从 0 变成 1。若一直是 0，看「节点」区的失败原因。
+
+角色选择页也加了一句判断提示：
+
+    通常：你现在用的这台（你在这里操作 DSH 的）= 主机；
+          另一台要被派活的电脑 = 副机。
+
+#### ⑤ 任务进度摘要
+
+长任务（agent 跑 10 分钟）原来只有展开详情才能看到「进行步骤」。
+现在**任务行下方**直接显示：
+
+    运行中 · 已跑 6m12s
+      最近：调用工具 Write · 共 23 步
+
+只对运行中的任务显示（已完成看结果摘要更有用），只取最后一条有内容的步骤。
+
+### 顺带修复
+
+- `lib/node/index.js` 的 `friendlyConnectError` import 已无用（被 explain-error
+  替代），删除
+- `explainError` 的取值路径逐层 try —— `String(err)` 在 `toString` 抛错时
+  会崩，而翻译层的职责是"绝不抛"（测试抓到的真 bug）
+
+### 测试
+
+- `test/explain-error.test.js` **20 条**：errno / 协议码全覆盖（断言 17 个
+  ERROR_CODE 都有专门翻译，不能落到兜底）/ HTTP / 文案特征 / 健壮性
+  （含 `toString` 抛错的恶意对象）/ 渲染
+- doc-drift 新增 88（翻译层覆盖面）、89（连接历史链路）、90（复制按钮 +
+  编号步骤 + 进度摘要）
+
+**写测试时又踩了一次"断言自己的问题"**：健壮性用例的消息里写了
+`String(v)`，而那个用例的 `toString` 是故意抛错的 → 断言在构造消息时
+自己先崩，误报成"实现抛错"。改用下标标识用例。
+
+```
+packaging   4 项
+doc-drift   126/126
+diag:inject 11 项
+tests       1007（1005 pass / 0 fail / 2 skip）
+lint        干净
+```
+
 ## [0.9.5] - 2026-10-20
 
 > **紧急修复：0.9.4 装上后 DSH 报激活失败，插件显示"异常"。**

package/lib/client.js

@@ -743,13 +743,56 @@ window.__ModuleLoader__.load({
             h('div', { className: 'dra-kv' }, h('span', { className: 'dra-k' }, '配置文件'), h('span', { className: 'dra-mono dra-ell', title: result.file }, result.file || '')),
             result.backup ? h('div', { className: 'dra-kv' }, h('span', { className: 'dra-k' }, '备份'), h('span', { className: 'dra-mono dra-ell', title: result.backup }, result.backup)) : null,
             h('div', { className: 'dra-sec' }, '下一步'),
-            h('div', { className: 'dra-empty' }, '**重启 DSH** 后生效。重启回来打开这个面板，就能看到完整功能了。'),
-            result.role === 'hub'
-              ? h('div', null,
-                h('div', { className: 'dra-sec' }, '副机怎么接进来'),
-                h('div', { className: 'dra-empty' }, '重启后这个面板会显示「副机接入」按钮，点它生成配对码，把码发给副机即可。'),
-              )
-              : null,
+            // ── 编号步骤（2026-10-20，体验提升 ③）─────────────────────
+            //
+            // 原来只有一句"重启 DSH 后生效"，用户不知道接下来分几步、
+            // 每步做什么、做完该看到什么。
+            //
+            // 现在给明确的编号流程，**每步一个动作 + 一个"你应该看到什么"**：
+            // 用户卡住时能立刻判断自己停在哪一步。
+            h('div', { style: { paddingLeft: '4px' } },
+              h('div', { className: 'dra-row', style: { alignItems: 'baseline' } },
+                h('span', { className: 'dra-badge' }, '1'),
+                h('span', { style: { flex: '1' } }, '重启 DSH'),
+                h('span', { className: 'dra-dim' }, '必须'),
+              ),
+              h('div', { className: 'dra-dim', style: { paddingLeft: '28px', marginBottom: '6px' } },
+                '关掉 DSH 窗口再打开。配置只在启动时读取。'),
+
+              result.role === 'hub'
+                ? h('div', null,
+                  h('div', { className: 'dra-row', style: { alignItems: 'baseline' } },
+                    h('span', { className: 'dra-badge' }, '2'),
+                    h('span', { style: { flex: '1' } }, '生成配对码'),
+                  ),
+                  h('div', { className: 'dra-dim', style: { paddingLeft: '28px', marginBottom: '6px' } },
+                    '重启后这个面板会出现「副机接入」按钮 —— 点它，复制那行 dshra1:// 开头的码。'),
+
+                  h('div', { className: 'dra-row', style: { alignItems: 'baseline' } },
+                    h('span', { className: 'dra-badge' }, '3'),
+                    h('span', { style: { flex: '1' } }, '在副机上粘贴'),
+                  ),
+                  h('div', { className: 'dra-dim', style: { paddingLeft: '28px', marginBottom: '6px' } },
+                    '副机也装本插件 → 打开面板 → 把码粘进「配对码」框 → 保存 → 重启副机 DSH。'),
+
+                  h('div', { className: 'dra-row', style: { alignItems: 'baseline' } },
+                    h('span', { className: 'dra-badge' }, '4'),
+                    h('span', { style: { flex: '1' } }, '等它连上'),
+                  ),
+                  h('div', { className: 'dra-dim', style: { paddingLeft: '28px' } },
+                    '回到这个面板 —— 「在线节点」会从 0 变成 1。',
+                    '若一直是 0，看「节点」区：那里会显示最后一次连接失败的原因和修法。'),
+                )
+                : h('div', null,
+                  h('div', { className: 'dra-row', style: { alignItems: 'baseline' } },
+                    h('span', { className: 'dra-badge' }, '2'),
+                    h('span', { style: { flex: '1' } }, '确认连上了主机'),
+                  ),
+                  h('div', { className: 'dra-dim', style: { paddingLeft: '28px' } },
+                    '重启后打开这个面板 —— 应显示「本机状态」而不是引导页。',
+                    '若又回到引导页，说明配置被覆盖了：看「最近一次错误」和日志尾巴。'),
+                ),
+            ),
           ),
         )
       }
@@ -771,6 +814,13 @@ window.__ModuleLoader__.load({
           head,
           h('div', { className: 'dra-body' },
             h('div', { className: 'dra-sec' }, switching ? '改成什么角色？' : '这台电脑要做什么？'),
+            // 判断提示（2026-10-20，体验提升 ③）：用户第一次打开时不知道选哪个。
+            // 实测最常见的困惑是"我要在另一台电脑上跑任务，那我这台算什么？"
+            switching
+              ? null
+              : h('div', { className: 'dra-dim', style: { marginBottom: '10px' } },
+                '通常：你现在用的这台（你在这里操作 DSH 的）= 主机；',
+                '另一台要被派活的电脑 = 副机。'),
             // 提示放在卡片**上方**：用户点完按钮后的反馈必须紧邻按钮，
             // 否则会被滚动位置藏在折叠线以下（实测踩过）。
             note ? h('div', { className: 'dra-err', style: { marginBottom: '8px' } }, note) : null,
@@ -946,6 +996,8 @@ window.__ModuleLoader__.load({
     function Panel() {
       const st = React.useState({
         loading: true, error: '', nodes: [], tasks: [], counts: null, caps: null,
+        // 连接尝试历史（体验提升 ①）：null = 还没拉到，空对象 = 拉到了但没记录
+        connection: null,
         // 'hub'    = 本机是派活方（有 UI 路由）
         // 'worker' = 本机是干活方（读 STATUS_PATH）
         // 'setup'  = 本机未配置（读 SETUP_STATE_PATH，显示引导）
@@ -1336,6 +1388,8 @@ window.__ModuleLoader__.load({
                   nodes: ov.nodes || [],
                   counts: ov.counts || null,
                   caps: ov.capabilities || null,
+                  // 连接尝试历史（体验提升 ①）：副机连不上时面板要能说清原因
+                  connection: ov.connection || null,
                   tasks: tk.tasks || [],
                 })
               })
@@ -1770,8 +1824,22 @@ window.__ModuleLoader__.load({
                 ? h('div', { className: 'dra-dim', style: { paddingLeft: '20px' } }, it.detail)
                 : null,
               !it.ok && it.fix
-                ? h('div', { className: 'dra-dim', style: { paddingLeft: '20px', marginTop: '2px' } },
-                  '↳ 怎么修：' + it.fix)
+                ? h('div', { style: { paddingLeft: '20px', marginTop: '2px' } },
+                  h('div', { className: 'dra-dim' }, '↳ 怎么修：' + it.fix),
+                  // 一键复制（2026-10-20，体验提升 ②）：
+                  // 修法里常含可直接粘贴的命令/YAML 片段，让用户手抄是纯粹的摩擦。
+                  // **只做复制，不做"一键修复"** —— 后者会改用户文件，风险 > 收益
+                  // （我们刚因为改 DSH 文件出过事故）。
+                  h('button', {
+                    className: 'dra-btn',
+                    style: { marginTop: '4px', padding: '2px 8px', fontSize: '11px' },
+                    onClick: function () {
+                      copyText(it.fix).then(function (ok) {
+                        setNote(ok ? '已复制修法到剪贴板' : '复制失败，请手动选中复制')
+                      })
+                    },
+                  }, '复制修法'),
+                )
                 : null,
             )
           }),
@@ -1873,8 +1941,60 @@ window.__ModuleLoader__.load({
       )
 
       // ── 节点 ──
+      //
+      // 空态不能只说"还没有节点接入"（2026-10-20，体验提升 ①）。
+      // 实测用户为此排查了两天：副机连不上时主机只显示「0 在线」，
+      // **没有任何原因**。现在把连接尝试历史渲染出来：
+      //   · 有过失败 → 显示"最后尝试 N 前 —— 人话原因 → 下一步做什么"
+      //   · 从没尝试过 → 说明"副机还没开始连"（方向完全不同！）
+      const conn = state.connection || { everConnected: false, byNode: [], recent: [] }
+      const fmtAgo = function (at) {
+        if (!at) return '未知时间'
+        const sec = Math.max(0, Math.round((Date.now() - at) / 1000))
+        if (sec < 60) return sec + ' 秒前'
+        if (sec < 3600) return Math.round(sec / 60) + ' 分钟前'
+        if (sec < 86400) return Math.round(sec / 3600) + ' 小时前'
+        return Math.round(sec / 86400) + ' 天前'
+      }
+
+      const connDiag = function () {
+        const fails = (conn.byNode || []).filter(function (e) { return e.result === 'fail' })
+        if (fails.length > 0) {
+          // 有失败记录：逐台显示最后一次失败的人话
+          return h('div', null,
+            fails.slice(0, 5).map(function (e) {
+              return h('div', { key: (e.nodeId || '') + (e.remote || ''), style: { marginBottom: '8px' } },
+                h('div', { className: 'dra-row', style: { alignItems: 'baseline' } },
+                  h('span', { className: 'dra-mono', style: { color: 'var(--dsw-alias-state-error-primary, currentColor)' } }, '✗'),
+                  h('span', { style: { flex: '1' } }, (e.nodeId || e.remote || '未知来源') + ' 连接失败'),
+                  h('span', { className: 'dra-dim' }, fmtAgo(e.at)),
+                ),
+                e.title
+                  ? h('div', { className: 'dra-dim', style: { paddingLeft: '20px' } }, e.title)
+                  : null,
+                e.hint
+                  ? h('div', { className: 'dra-dim', style: { paddingLeft: '20px' } }, '→ ' + e.hint)
+                  : null,
+                e.raw
+                  ? h('div', { className: 'dra-dim', style: { paddingLeft: '20px', opacity: 0.6 } }, '原始：' + e.raw)
+                  : null,
+              )
+            }),
+            conn.everConnected
+              ? null
+              : h('div', { className: 'dra-dim', style: { marginTop: '4px' } },
+                '这台副机从未成功连上过 —— 先确认副机上的插件已配置 role: worker 并填了正确的 hubUrl。'),
+          )
+        }
+        // 没有任何失败记录：区分"从没尝试"与"连上过但当前离线"
+        return h('div', { className: 'dra-empty' },
+          conn.everConnected
+            ? '副机之前连上过，现在不在线 —— 检查副机 DSH 是否在跑。'
+            : '还没有任何副机尝试连接。在副电脑上装本插件，把 config.role 设为 worker 并填 hubUrl（或用面板的配对码）。')
+      }
+
       const nodeRows = state.nodes.length === 0
-        ? h('div', { className: 'dra-empty' }, '还没有节点接入。在副电脑上装本插件并把 config.role 设为 worker。')
+        ? connDiag()
         : state.nodes.map(function (n) {
           // 资源徽章：有遥测才显示（首次采样前 cpuPct 为 null → 不误导）
           const r = n.resource
@@ -2156,6 +2276,37 @@ window.__ModuleLoader__.load({
         const liveSec = t.status === 'running' && t.startedAt
           ? Math.max(0, Math.round((Date.now() - t.startedAt) / 1000))
           : 0
+
+        // ── 进度摘要（2026-10-20，体验提升 ⑤）─────────────────────────
+        //
+        // 原来只有展开详情才能看到「进行步骤」。但长任务（agent 跑 10 分钟）
+        // 用户最想知道的是"它现在在干什么"—— 为此点开详情是多余的摩擦。
+        //
+        // 这里在**任务行下方**加一行摘要：最后一步 + 总步数。
+        //   · 只对运行中的任务显示（已完成的任务看结果摘要更有用）
+        //   · 只取最后一条有 detail 的（tool/assistant 事件才有内容）
+        let progressLine = null
+        if (t.status === 'running' && Array.isArray(t.progressTail) && t.progressTail.length > 0) {
+          const tail = t.progressTail
+          // 从后往前找第一条带 detail 的（"started"/"agent-start" 这类没有内容）
+          let last = null
+          for (let i = tail.length - 1; i >= 0; i -= 1) {
+            const p = tail[i]
+            if (p && typeof p.detail === 'string' && p.detail.trim() !== '') { last = p; break }
+          }
+          if (last) {
+            const phase = typeof last.phase === 'string' ? last.phase : ''
+            progressLine = h('div', {
+              className: 'dra-dim',
+              style: { paddingLeft: '20px', fontSize: '11px', marginTop: '-2px' },
+              title: last.detail,
+            },
+              '最近：' + (phase === 'tool' ? '调用工具 ' : '') + last.detail.slice(0, 120),
+              ' · 共 ' + tail.length + ' 步',
+            )
+          }
+        }
+
         return h('div', { key: t.taskId },
           h('div', {
             className: 'dra-row' + (isSel ? ' sel' : ''),
@@ -2169,6 +2320,7 @@ window.__ModuleLoader__.load({
               ? h('span', { className: 'dra-dim', title: '已运行时长' }, '已跑 ' + fmtDur(liveSec * 1000))
               : (t.durationMs ? h('span', { className: 'dra-dim' }, fmtDur(t.durationMs)) : null),
           ),
+          progressLine,
           isSel ? h(TaskDetail, {
             task: t, detail: detail, caps: caps, onCancel: cancel, onPull: pull,
             onApprove: approve, onReject: reject,

package/lib/e2e.js

@@ -97,8 +97,49 @@ export function normalizeE2EPub(raw) {
   return raw
 }
 
+/**
+ * X25519 PKCS#8 私钥的 DER 前缀（16 字节）。
+ *
+ * 结构：SEQUENCE { INTEGER 0, SEQUENCE { OID 1.3.101.110 (X25519) },
+ *                OCTET STRING { OCTET STRING(32 字节原始标量) } }
+ * 后接 32 字节标量即完整私钥。
+ */
+const X25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex')
+
+/**
+ * 由 base64url 的 32 字节标量构造 X25519 私钥。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ⚠ 为什么用 DER 而不是 JWK（2026-10-20 CI 抓到的真实缺陷）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 原实现：`createPrivateKey({ key: { kty:'OKP', crv:'X25519', d: b64, x: '' }, format:'jwk' })`
+ *
+ * 在本地 Node 24.18 上能过，但在 GitHub Actions 的 `ubuntu-latest / node 24.x`
+ * 上抛 **`ERR_CRYPTO_INVALID_JWK`** —— 那个版本对 JWK 的 `x` 校验更严
+ * （空串不是合法 base64url；省略 `x` 同样被拒）。
+ *
+ * 后果很隐蔽：E2E 握手失败 → 测试只看到
+ * `timeout waiting for e2e session on test-worker`，**真因被完全掩盖**。
+ *
+ * ── 修法 ────────────────────────────────────────────────────────────────
+ *
+ * 直接用 **DER** 构造：X25519 私钥的 PKCS#8 就是固定 16 字节前缀 + 32 字节
+ * 标量。这条路径**不经过 JWK 校验**，跨 Node 小版本稳定。
+ *
+ * 实测验证：DER 构造出的私钥导出的公钥 `x` 与原始 JWK 完全一致，
+ * 且 DH 协商结果与正常生成的密钥对一致。
+ */
 function x2PrivateKeyFromB64(b64) {
-  return createPrivateKey({ key: { kty: 'OKP', crv: 'X25519', d: b64, x: '' }, format: 'jwk' })
+  const raw = Buffer.from(String(b64), 'base64url')
+  if (raw.length !== X2_PUB_BYTES) {
+    throw new Error(`bad x25519 private key length: ${raw.length} (expect ${X2_PUB_BYTES})`)
+  }
+  return createPrivateKey({
+    key: Buffer.concat([X25519_PKCS8_PREFIX, raw]),
+    format: 'der',
+    type: 'pkcs8',
+  })
 }
 
 function x2PublicKeyFromB64(b64) {

package/lib/explain-error.js

@@ -0,0 +1,472 @@
+/**
+ * 错误翻译层（2026-10-20，用户体验提升 ④）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 为什么需要它
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 实测用户反馈：**出了问题不知道原因**。而原始错误长这样：
+ *
+ *     connect timeout after 15000ms
+ *     ECONNREFUSED 100.86.48.54:19387
+ *     HTTP 401 {"error":"unauthorized"}
+ *     task t-mvc2qkfcgo32w terminal: timeout after 40000ms
+ *     EPERM: operation not permitted, rename 'C:\Users\...\templates.json.tmp-...'
+ *
+ * 用户看到这些只能猜。而本项目**已经**在 `lib/setup.js` 里有一份
+ * `friendlyConnectError` —— 但它只覆盖 5 类网络错误，且没用到协议错误码。
+ *
+ * 本模块把翻译**统一到一处**：
+ *   · 网络层（Node errno）
+ *   · 协议层（ERROR_CODE 的 17 个码）
+ *   · 面板层（HTTP 状态码）
+ *   · 文件系统（EPERM/ENOENT 等）
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 设计原则
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ *   · **每条都带"下一步做什么"** —— 只说"连接失败"等于没说
+ *   · **保留原始信息**（`raw` 字段）—— 翻译不能丢排查线索
+ *   · **绝不抛**：任何输入都返回一个结构，最差也回退到原始 message
+ *   · **不猜**：拿不准的不编造原因，如实说"未知，请附上原始错误"
+ */
+
+import { ERROR_CODE } from './protocol.js'
+
+/** 统一的翻译结果。 */
+function result({ title, detail = '', hint = '', raw = '', level = 'error' }) {
+  return { title, detail, hint, raw, level }
+}
+
+/**
+ * 网络层错误（Node errno）→ 人话。
+ *
+ * @param {string} code errno，如 ECONNREFUSED
+ * @param {object} [o]
+ * @param {string} [o.where] 目标地址（host:port）
+ * @param {boolean} [o.isHub] 出错方是不是主机侧（影响措辞）
+ */
+function translateErrno(code, { where = '', isHub = false } = {}) {
+  const at = where !== '' ? where : (isHub ? '副机' : '主机')
+  const other = isHub ? '副机' : '主机'
+
+  switch (code) {
+    case 'ECONNREFUSED':
+      return result({
+        title: `${at} 上没有服务在监听`,
+        detail: '连接被主动拒绝 —— 对端机器在，但那个端口没程序在听。',
+        hint: isHub
+          ? `检查：① 副机的 DSH 是否在跑；② 副机配置的 hubUrl 端口是否与主机的 listenPort 一致（默认 19387）；③ 副机是否已设 role: worker。`
+          : `检查：① 主机的 DSH 是否在跑；② 主机插件是否成功监听（看面板「环境体检」）；③ IP/端口是否写对。`,
+      })
+
+    case 'ETIMEDOUT':
+    case 'ETIMEDOUT_':
+      return result({
+        title: `${at} 连不上（超时）`,
+        detail: '数据包发出去了但没回应 —— 通常是网络不通或防火墙拦截。',
+        hint: '检查：① 两台机器能否互 ping（Tailscale 用 tailscale status 看是否 online）；'
+          + '② 主机防火墙是否放行该端口；③ 是否在同一局域网但路由器开了 AP 隔离。',
+      })
+
+    case 'EHOSTUNREACH':
+    case 'ENETUNREACH':
+      return result({
+        title: `到 ${at} 的网络不可达`,
+        detail: '本机没有到那个地址的路由 —— 地址可能不在任何已连接的网段。',
+        hint: `检查：① Tailscale 是否已连接（tailscale status）；② 是否两台机器在同一局域网；`
+          + `③ IP 是否写错（Tailscale IP 形如 100.x.x.x）。`,
+      })
+
+    case 'ENOTFOUND':
+    case 'EAI_AGAIN':
+      return result({
+        title: `解析不了 ${at} 的主机名`,
+        detail: 'DNS 查不到这个名字。',
+        hint: 'hubUrl 里建议直接写 **IP**（如 100.86.48.54 或 192.168.1.10），不要写主机名。',
+      })
+
+    case 'EACCES':
+    case 'EPERM':
+      return result({
+        title: '系统拒绝了这次操作（权限不足）',
+        detail: '不是网络问题 —— 是操作系统层面的权限拦截。',
+        hint: '如果是文件操作：检查目录权限、文件是否被别的程序占用；'
+          + '如果是端口：换一个端口（<1024 需要管理员）。',
+      })
+
+    case 'ECONNRESET':
+      return result({
+        title: `${at} 主动断开了连接`,
+        detail: '连接建立后又被对方关闭 —— 可能是对端重启、崩溃，或协议不匹配。',
+        hint: `检查：① ${other}的 DSH 是否刚重启过（重连通常会自动恢复）；`
+          + '② 两端插件版本是否一致（版本差太多会握手失败）。',
+      })
+
+    case 'EPIPE':
+      return result({
+        title: '连接已断开，写入失败',
+        detail: '对端已经关闭，还在往管道里写。',
+        hint: '通常会自动重连。若持续出现，检查对端进程是否在崩溃重启。',
+      })
+
+    case 'ENOENT':
+      return result({
+        title: '找不到这个文件或目录',
+        detail: '路径不存在 —— 可能是拼写错误，或那个目录被删了。',
+        hint: '检查配置里的路径（尤其 roots / uiPullRoot）是否真实存在。',
+      })
+
+    case 'EADDRINUSE':
+      return result({
+        title: '端口已被占用',
+        detail: '这个端口已经有别的程序在监听了。',
+        hint: '换一个端口（配置里改 listenPort），或先关掉占用它的程序。'
+          + '查占用：netstat -ano | findstr :19387',
+      })
+
+    case 'EADDRNOTAVAIL':
+      return result({
+        title: '这个 IP 不属于本机',
+        detail: '想绑的地址在本机网卡上不存在（IP 变了，或写错了）。',
+        hint: '检查配置里的 listenHost。留空则自动选择（推荐）—— '
+          + '会自动挑 Tailscale IP 或局域网 IP。',
+      })
+
+    default:
+      return null
+  }
+}
+
+/**
+ * 协议错误码 → 人话。
+ *
+ * @param {string} code ERROR_CODE 的值
+ * @param {object} [o]
+ * @param {boolean} [o.isHub] 保留参数（协议错误码的文案对两端通用，暂未分支）
+ */
+function translateProtocolCode(code, { isHub: _isHub = false } = {}) {
+  switch (code) {
+    case ERROR_CODE.PROTOCOL_MISMATCH:
+      return result({
+        title: '两端插件版本不兼容',
+        detail: '协议版本号对不上 —— 一端太旧或太新。',
+        hint: '把**两台机器**的 dsh-remote-agent 升级到同一版本（npm i -g dsh-remote-agent@latest）。',
+      })
+
+    case ERROR_CODE.UNAUTHORIZED:
+      return result({
+        title: '鉴权失败（token 不对）',
+        detail: '主机拒绝了副机的凭证。',
+        hint: '重新生成配对码：主机面板「副机接入」→ 复制新的 dshra1:// 整行 → '
+          + '在副机重新粘贴 → 重启副机 DSH。',
+      })
+
+    case ERROR_CODE.DUPLICATE_NODE:
+      return result({
+        title: '节点 ID 重复',
+        detail: '已经有一台同 ID 的副机在线 —— 两台机器用了同一个 nodeId。',
+        hint: '在副机面板「本机标识」里改一个不同的节点 ID（或留空自动用主机名），然后重启。',
+      })
+
+    case ERROR_CODE.HUB_IDENTITY_MISMATCH:
+      return result({
+        title: '主机身份指纹变了',
+        detail: '副机之前钉住过这台主机，但现在的指纹对不上 —— 可能是换了主机，或主机身份文件被重建。',
+        hint: '如果确实是同一台主机（身份文件被删过）：在副机删掉 '
+          + '~/.dsh-remote-agent/hub-pin.json 后重启。如果是换了主机：重新生成配对码。',
+      })
+
+    case ERROR_CODE.HUB_IDENTITY_PENDING:
+      return result({
+        title: '主机身份待确认',
+        detail: '首次连接，副机在等主机出示身份证明。',
+        hint: '正常流程会自动完成。若卡住：检查主机是否是较新版本（旧版没有身份签名）。',
+      })
+
+    case ERROR_CODE.E2E_RESET:
+      return result({
+        title: '加密会话已重置',
+        detail: '主机重启过，之前的密钥失效了。',
+        hint: '自动重新握手，通常无需操作。若持续出现，检查两端版本是否一致。',
+      })
+
+    case ERROR_CODE.E2E_REQUIRED:
+      return result({
+        title: '要求加密但握手没完成',
+        detail: '业务帧必须以密文发送，但当前连接还没有加密会话。',
+        hint: '通常是中继模式下的临时状态。若持续：重启两端 DSH。',
+      })
+
+    case ERROR_CODE.WORKSPACE_DENIED:
+      return result({
+        title: '工作区被拒绝（路径越界）',
+        detail: '请求的路径不在该副机允许的 roots 范围内。',
+        hint: '在副机配置里把该目录加进 roots（必须是绝对路径、必须真实存在），然后重启副机。',
+      })
+
+    case ERROR_CODE.ARTIFACT_DENIED:
+      return result({
+        title: '产物被拒绝',
+        detail: '该文件不在可拉取的产物清单里（可能被判为 intermediate 或 other）。',
+        hint: '只有 role:final 的文件能拉。用 remote_manifest 看清单；'
+          + '如需放宽，用 artifactRules 配置调整分类规则。',
+      })
+
+    case ERROR_CODE.ARTIFACT_MISSING:
+      return result({
+        title: '产物文件不见了',
+        detail: '清单里有，但副机上那个文件已经被删或改名。',
+        hint: '重新跑一次任务，或让副机确认该文件还在原路径。',
+      })
+
+    case ERROR_CODE.ARTIFACT_TOO_LARGE:
+      return result({
+        title: '产物超过大小上限',
+        detail: '单个文件太大，超出协议允许的单帧/单文件上限。',
+        hint: '在副机上压缩后再拉，或直接用面板的「工作区共享（SMB）」映射目录访问。',
+      })
+
+    case ERROR_CODE.HASH_MISMATCH:
+      return result({
+        title: '文件校验失败（内容不一致）',
+        detail: '传输过程中内容变了 —— 通常是文件在传的时候被修改，或断点续传的偏移算错了。',
+        hint: '重试一次（会自动从头传）。若持续：确认副机上那个文件没有被其它程序正在写。',
+      })
+
+    case ERROR_CODE.FS_TIMEOUT:
+      return result({
+        title: '文件操作超时',
+        detail: '副机在时限内没返回结果 —— 可能它正忙，或那个目录特别大。',
+        hint: '稍后重试。若是 grep 大目录，缩小 path 范围或用更精确的 pattern。',
+      })
+
+    case ERROR_CODE.TASK_UNKNOWN:
+      return result({
+        title: '找不到这个任务',
+        detail: '任务 ID 不存在 —— 可能已被清理，或副机重启后丢了记录。',
+        hint: '用 remote_nodes 看当前任务列表。若任务确实该在，检查副机是否重启过。',
+      })
+
+    case ERROR_CODE.TASK_DUPLICATE:
+      return result({
+        title: '任务 ID 重复',
+        detail: '这个 taskId 已经存在了。',
+        hint: '通常是重试逻辑的问题 —— 换一个新的 taskId，或先查 remote_status。',
+      })
+
+    case ERROR_CODE.INTERNAL:
+      return result({
+        title: '内部错误',
+        detail: '插件内部出了意外。',
+        hint: '这通常是 bug。请附上原始错误信息提 issue：'
+          + 'https://github.com/zbzbhs/dsh-remote-agent/issues',
+      })
+
+    default:
+      return null
+  }
+}
+
+/** HTTP 状态码 → 人话（面板/路由层）。 */
+function translateHttp(status) {
+  const n = Number(status)
+  if (!Number.isFinite(n)) return null
+  switch (n) {
+    case 401:
+      return result({
+        title: '面板鉴权失败',
+        detail: 'DSH 的连接围栏拒绝了这次请求（Host/Origin 校验或 cookie 失效）。',
+        hint: '刷新页面。若持续：确认你是从 DSH 桌面窗口打开面板，而不是别的浏览器标签。',
+      })
+    case 403:
+      return result({
+        title: '没有权限',
+        detail: '服务端明确拒绝了这次操作。',
+        hint: '检查当前 DSH 会话的权限设置。',
+      })
+    case 404:
+      return result({
+        title: '接口不存在',
+        detail: '请求的路径没注册 —— 通常是**插件没被加载**，或版本太旧没有这个接口。',
+        hint: '检查：① 插件是否已安装并启用；② 版本是否过旧（面板底部有版本号）。',
+      })
+    case 405:
+      return result({
+        title: '请求方法不对',
+        detail: '这个接口不接受该 HTTP 方法。',
+        hint: '通常是面板与插件版本不匹配 —— 升级插件后刷新页面。',
+      })
+    case 409:
+      return result({
+        title: '冲突',
+        detail: '目标状态已被别人改过（例如同时两个人改配置）。',
+        hint: '刷新页面看最新状态，再重试。',
+      })
+    case 500:
+      return result({
+        title: '服务端出错',
+        detail: '插件内部抛了异常。',
+        hint: '看 DSH 日志里的 [remote-agent] 行。这通常是 bug，欢迎提 issue。',
+      })
+    case 502:
+    case 503:
+    case 504:
+      return result({
+        title: '副机暂时不可用',
+        detail: '主机连不上副机，或副机正在重启。',
+        hint: '稍后重试。检查副机是否在线（面板「节点」区）。',
+      })
+    default:
+      return null
+  }
+}
+
+/**
+ * 主入口：把任意错误翻译成人话。
+ *
+ * 识别顺序：errno 码 → 协议错误码 → HTTP 状态码 → 已知文案特征 → 兜底。
+ *
+ * @param {any} err 错误对象 / 字符串 / {code, message}
+ * @param {object} [o]
+ * @param {string} [o.where] 目标地址（host:port），用于措辞
+ * @param {boolean} [o.isHub] 出错方是不是主机侧
+ * @param {string} [o.context] 上下文（"连接副机" / "拉取产物" 等），用于兜底文案
+ * @returns {{title:string, detail:string, hint:string, raw:string, level:string}}
+ */
+export function explainError(err, { where = '', isHub = false, context = '' } = {}) {
+  // 提取原始信息（尽量不丢线索）
+  //
+  // ⚠ 这里必须**逐层 try**（2026-10-20 测试抓到的真 bug）：
+  // `String(err)` 会调用 err.toString()，而它可能是被用户/第三方对象覆盖的
+  // 会抛错的实现。原写法 `String(err.message ?? err)` 在 message 为 undefined
+  // 时退化成 `String(err)` → 整个翻译层崩掉。
+  // 翻译层的职责是"绝不抛"，所以每个可能抛的取值都单独兜住。
+  let raw = ''
+  let code = ''
+  let message = ''
+  const safeString = (v) => {
+    try {
+      if (typeof v === 'string') return v
+      if (v === null || v === undefined) return ''
+      return String(v)
+    } catch {
+      return '(无法转成字符串)'
+    }
+  }
+  try {
+    if (typeof err === 'string') {
+      raw = err
+      message = err
+    } else if (err && typeof err === 'object') {
+      // message 优先；取不到再退回整个对象（但用 safeString 包住）
+      let m = ''
+      try {
+        m = typeof err.message === 'string' ? err.message : ''
+      } catch {
+        /* message getter 抛错 */
+      }
+      raw = m !== '' ? m : safeString(err)
+      message = m
+      try {
+        code = typeof err.code === 'string' ? err.code : ''
+      } catch {
+        /* code getter 抛错 */
+      }
+    }
+  } catch {
+    raw = '(无法读取错误对象)'
+  }
+
+  // 1. errno（Node 网络/文件系统错误）
+  if (code !== '') {
+    const t = translateErrno(code, { where, isHub })
+    if (t) return { ...t, raw }
+  }
+
+  // 2. 协议错误码
+  if (code !== '') {
+    const t = translateProtocolCode(code, { isHub })
+    if (t) return { ...t, raw }
+  }
+
+  // 3. 从 message 里捞协议错误码（很多地方只把 code 拼进文案）
+  for (const c of Object.values(ERROR_CODE)) {
+    if (typeof c === 'string' && c !== '' && message.includes(c)) {
+      const t = translateProtocolCode(c, { isHub })
+      if (t) return { ...t, raw }
+    }
+  }
+
+  // 4. HTTP 状态码（message 形如 "HTTP 401" 或 "401 Unauthorized"）
+  const httpMatch = /\b(4\d\d|5\d\d)\b/.exec(message)
+  if (httpMatch) {
+    const t = translateHttp(httpMatch[1])
+    if (t) return { ...t, raw }
+  }
+
+  // 5. 常见文案特征（Node/我们自己的实现里的固定串）
+  if (/timeout after \d+ms/i.test(message) || /timed out after \d+ms/i.test(message)) {
+    const ms = /after (\d+)ms/i.exec(message)
+    const sec = ms ? Math.round(Number(ms[1]) / 1000) : null
+    return {
+      ...result({
+        title: '操作超时',
+        detail: sec !== null ? `等了 ${sec} 秒没收到回应。` : '等待回应超时。',
+        hint: isHub
+          ? '检查副机是否在线、是否正忙。若是长任务，用更长的 timeoutMs 重派。'
+          : '检查主机是否在线、网络是否稳定。',
+      }),
+      raw,
+    }
+  }
+
+  if (/handshake timeout/i.test(message)) {
+    return {
+      ...result({
+        title: '握手超时',
+        detail: 'TCP 连上了，但 WebSocket/协议握手没在时限内完成。',
+        hint: '通常是**两端版本差异太大**，或对端那个端口上跑的不是本插件。'
+          + '确认：① 端口号是否写对（默认 19387）；② 两端插件版本是否一致。',
+      }),
+      raw,
+    }
+  }
+
+  if (/not lossless JSON|invalid output/i.test(message)) {
+    return {
+      ...result({
+        title: '数据格式异常',
+        detail: '插件返回的数据里有无法序列化的值（这通常是 bug）。',
+        hint: '请附上原始错误提 issue。',
+      }),
+      raw,
+    }
+  }
+
+  // 6. 兜底：不编造原因，如实说
+  return {
+    ...result({
+      title: context !== '' ? `${context}失败` : '出错了',
+      detail: message !== '' ? message : '没有更多信息。',
+      hint: '如果看不懂这条错误，请把**原始错误**整段附上提 issue：'
+        + 'https://github.com/zbzbhs/dsh-remote-agent/issues',
+      level: 'warn',
+    }),
+    raw,
+  }
+}
+
+/**
+ * 把翻译结果渲染成一行可读文本（日志/CLI 用；面板自己排版）。
+ *
+ * @param {ReturnType<typeof explainError>} t
+ * @returns {string}
+ */
+export function formatExplained(t) {
+  const lines = [t.title]
+  if (t.detail) lines.push(`  ${t.detail}`)
+  if (t.hint) lines.push(`  → ${t.hint}`)
+  return lines.join('\n')
+}

package/lib/hub/node-registry.js

@@ -35,6 +35,8 @@ import {
 // 视图投影共享层：registry 给工具用的任务视图与 UI 路由共用同一份白名单。
 import { taskView as taskProjection } from './views.js'
 import { errText } from './hub-util.js'
+// 统一错误翻译层（2026-10-20，体验提升 ①）：连接失败时给面板"人话 + 下一步"。
+import { explainError } from '../explain-error.js'
 import { withIngest } from './registry-ingest.js'
 import { withHandshake } from './registry-handshake.js'
 
@@ -78,6 +80,19 @@ class NodeRegistryCore {
     this.audit = audit && typeof audit.record === 'function' ? audit : null
     /** nodeId → rec */
     this.nodes = new Map()
+    /**
+     * 连接尝试历史（2026-10-20，体验提升 ①）。
+     *
+     * 问题：副机连不上时，主机只显示「0 在线」，**没有任何原因**。
+     * 实测用户为此排查了两天（重启回引导页、19387 不监听、SMB 密码…）。
+     *
+     * 这里记**每一次连接尝试的结果**（成功/失败 + 原因 + 时间 + 远端地址），
+     * 面板据此显示"最后尝试 2 分钟前 —— 握手超时 → 检查…"。
+     *
+     * 上限 50 条（环形）：这是给人看的诊断线索，不是审计日志
+     * （审计是 audit.jsonl，那是给合规/追溯用的）。
+     */
+    this.connectionLog = []
     /** 等 hello 的连接 */
     this.pending = new Set()
     /** taskId → NodeJS.Timeout（两阶段审批的自动拒绝定时器，提案 #2） */
@@ -972,6 +987,69 @@ class NodeRegistryCore {
     }))
   }
 
+  // ─────────────────────────── 连接尝试历史 ───────────────────────────
+
+  /**
+   * 记一次连接尝试（2026-10-20，体验提升 ①）。
+   *
+   * @param {object} o
+   * @param {'ok'|'fail'} o.result
+   * @param {string} [o.code] 失败码（协议错误码 / errno / 'hello-timeout' 等）
+   * @param {string} [o.message] 原始错误文案
+   * @param {string} [o.nodeId] 若已知
+   * @param {string} [o.remote] 远端地址（IP:port 或 IP）
+   * @param {string} [o.transport] 'direct' | 'relay'
+   */
+  noteConnectionAttempt({ result, code = '', message = '', nodeId = '', remote = '', transport = '' } = {}) {
+    try {
+      const entry = {
+        at: Date.now(),
+        result: result === 'ok' ? 'ok' : 'fail',
+        code: typeof code === 'string' ? code : '',
+        message: typeof message === 'string' ? message.slice(0, 300) : '',
+        nodeId: typeof nodeId === 'string' ? nodeId : '',
+        remote: typeof remote === 'string' ? remote : '',
+        transport: typeof transport === 'string' ? transport : '',
+      }
+      // 失败时附上人话解释（面板直接用，不用再翻译一遍）
+      if (entry.result === 'fail') {
+        try {
+          const ex = explainError({ code: entry.code, message: entry.message }, { isHub: true, context: '副机接入' })
+          entry.title = ex.title
+          entry.detail = ex.detail
+          entry.hint = ex.hint
+        } catch {
+          /* 翻译失败不影响记录 */
+        }
+      }
+      this.connectionLog.push(entry)
+      // 环形上限 50：这是诊断线索，不是审计
+      if (this.connectionLog.length > 50) this.connectionLog.splice(0, this.connectionLog.length - 50)
+    } catch {
+      /* 诊断记录绝不能影响连接流程本身 */
+    }
+  }
+
+  /**
+   * 取连接尝试历史（新的在前）+ 每台已知节点的最后状态。
+   *
+   * @param {number} [limit]
+   */
+  connectionReport(limit = 20) {
+    const recent = this.connectionLog.slice(-Math.max(1, limit)).reverse()
+    // 按 nodeId 归并：每台机器最后一次尝试是什么结果
+    const byNode = new Map()
+    for (const e of this.connectionLog) {
+      if (e.nodeId !== '') byNode.set(e.nodeId, e)
+    }
+    return {
+      recent,
+      byNode: [...byNode.entries()].map(([k, v]) => ({ nodeId: k, ...v })),
+      // 有没有过任何成功的连接 —— 面板据此区分"从没连上过"与"连上又断了"
+      everConnected: this.connectionLog.some((e) => e.result === 'ok'),
+    }
+  }
+
   // ─────────────────────────── 生命周期 ───────────────────────────
 
   markOffline(nodeId, reason) {

package/lib/hub/registry-handshake.js

@@ -242,6 +242,18 @@ export function withHandshake(Base) {
 
       if (transport === 'direct') this.sendWelcome(rec)
       else this.sendIdentityFrame(rec) // relay：hub 在握手期对副机静默，身份帧必须在上线后追发
+      // 记一次成功的连接尝试（2026-10-20，体验提升 ①）——
+      // 面板据此区分"从没连上过"与"连上又断了"，这是排查方向的分水岭。
+      try {
+        this.noteConnectionAttempt({
+          result: 'ok',
+          nodeId: hello.nodeId,
+          remote: remoteOf(conn),
+          transport,
+        })
+      } catch {
+        /* 诊断记录绝不能影响上线流程 */
+      }
       this.log('info', 'node online', { nodeId: hello.nodeId, os: hello.os, transport })
       return rec
     }
@@ -388,6 +400,20 @@ export function withHandshake(Base) {
 
     /** 在指定连接上回 error 帧然后关闭。 */
     rejectConn(conn, code, message, nodeId) {
+      // 记一次失败的连接尝试（2026-10-20，体验提升 ①）——
+      // 副机连不上时，面板要能说清"为什么"，而不是只显示 0 在线。
+      try {
+        this.noteConnectionAttempt({
+          result: 'fail',
+          code: typeof code === 'string' ? code : '',
+          message: typeof message === 'string' ? message : '',
+          nodeId: typeof nodeId === 'string' ? nodeId : '',
+          remote: remoteOf(conn),
+          transport: 'direct',
+        })
+      } catch {
+        /* 诊断记录绝不能影响拒绝流程本身 */
+      }
       try {
         conn.send(encodeFrame(envelope(HUB_TO_NODE.ERROR, { code, message, nodeId })))
       } catch {
@@ -401,3 +427,21 @@ export function withHandshake(Base) {
     }
   }
 }
+
+/**
+ * 从连接对象上尽力取远端地址（用于诊断记录）。
+ * WSConnection 不一定暴露 remote，取不到就返回空串。
+ */
+function remoteOf(conn) {
+  try {
+    const s = conn?.socket
+    const addr = s?.remoteAddress
+    const port = s?.remotePort
+    if (typeof addr === 'string' && addr !== '') {
+      return typeof port === 'number' ? `${addr}:${port}` : addr
+    }
+  } catch {
+    /* 取不到就算了 */
+  }
+  return ''
+}

package/lib/hub/ui-routes.js

@@ -441,9 +441,37 @@ export function registerUiRoutes({
     if (req.method !== 'GET') return writeJson(res, 405, { error: 'method' })
     const nodes = registry.list().map(nodeView)
     const tasks = registry.listTasks().map((t) => registry.taskView(t))
+    // 连接尝试历史（2026-10-20，体验提升 ①）：副机连不上时面板要能说清原因。
+    // 逐字段投影（不 spread）—— 与其他 UI 响应同一条硬规则。
+    const connReport = (() => {
+      try {
+        const r = registry.connectionReport(20)
+        const mapEntry = (e) => ({
+          at: Number.isFinite(e.at) ? e.at : 0,
+          result: e.result === 'ok' ? 'ok' : 'fail',
+          code: typeof e.code === 'string' ? e.code : '',
+          nodeId: typeof e.nodeId === 'string' ? e.nodeId : '',
+          remote: typeof e.remote === 'string' ? e.remote : '',
+          title: typeof e.title === 'string' ? e.title : '',
+          detail: typeof e.detail === 'string' ? e.detail : '',
+          hint: typeof e.hint === 'string' ? e.hint : '',
+          raw: typeof e.message === 'string' ? e.message : '',
+        })
+        return {
+          everConnected: r.everConnected === true,
+          byNode: Array.isArray(r.byNode) ? r.byNode.slice(0, 20).map(mapEntry) : [],
+          recent: Array.isArray(r.recent) ? r.recent.slice(0, 20).map(mapEntry) : [],
+        }
+      } catch {
+        // 诊断数据取不到不该让整个面板挂掉
+        return { everConnected: false, byNode: [], recent: [] }
+      }
+    })()
     writeJson(res, 200, {
       ok: true,
       nodes,
+      // 连接尝试历史：面板据此显示"最后尝试 2 分钟前 —— 握手超时 → …"
+      connection: connReport,
       counts: {
         nodes: nodes.length,
         online: nodes.filter((n) => n.online).length,

package/lib/node/index.js

@@ -45,9 +45,12 @@ import { expandPairConfig } from '../pairing.js'
 import { selectRunner } from './runner.js'
 // 资源遥测：CPU（增量）/内存/负载采样，经 node/resource 帧上报 hub。
 import { RESOURCE_INTERVAL_MS, createResourceSampler } from './resource.js'
-// friendlyConnectError 来自向导的纯逻辑层（零依赖、无副作用）——
-// worker 的 error 事件与 --doctor 的网络探活共用同一份"怎么修"口径。
-import { friendlyConnectError } from '../setup.js'
+// 统一错误翻译层（2026-10-20，体验提升 ④）：覆盖协议错误码（17 个）+ HTTP
+// 状态 + errno，每条都给"下一步做什么"。面板与日志共用同一份口径。
+//
+// 注：原先这里还 import 了 setup.js 的 friendlyConnectError，2026-10-20 起
+// 运行时错误统一走 explain-error.js（覆盖面更广），那个 import 已无用。
+import { explainError, formatExplained } from '../explain-error.js'
 import { scanRepos } from './repos.js'
 import { TaskEngine } from './task-engine.js'
 import { TaskStore } from './task-store.js'
@@ -655,6 +658,18 @@ function startWorker(ctx, config) {
 
   /* 6) 发送助手：永不抛、失败即丢帧（断连期间任务照跑） ---------------- */
   let lastError = ''
+  /**
+   * 最近一次连接失败的结构化详情（2026-10-20，体验提升 ①）。
+   *
+   * `lastError` 只是原始字符串，面板没法据此给用户"下一步做什么"。
+   * 这里存翻译后的三件套：{ at, title, detail, hint, raw, code }。
+   *
+   * 面板据此显示：
+   *   ✗ 最后尝试 2 分钟前 —— 主机上没有服务在监听
+   *      → 检查：① 主机的 DSH 是否在跑；② 端口是否写对…
+   *      原始错误：connect ECONNREFUSED 100.86.48.54:19387
+   */
+  let lastErrorDetail = null
   const send = (type, data, opts) => {
     try {
       return transport.send(type, data, opts) === true
@@ -1104,10 +1119,25 @@ function startWorker(ctx, config) {
   })
   on('error', (err) => {
     lastError = msgOf(err)
-    // 底层错误码（ECONNREFUSED 等）对小白是天书。这里加一行"哪里没对 + 怎么修"
-    // 的人话版本；原始错误照记（排查仍需要）。映射表在 lib/setup.js 的
-    // friendlyConnectError，与 --doctor 的网络探活共用同一份口径。
-    logger.warn(`连接问题：${friendlyConnectError(err, {})}`, { nodeId, error: lastError })
+    // 底层错误码（ECONNREFUSED 等）对小白是天书。这里用**统一翻译层**
+    // （lib/explain-error.js）给出"哪里没对 + 下一步做什么"；原始错误照记
+    // （排查仍需要）。
+    //
+    // 2026-10-20 改：从 setup.js 的 friendlyConnectError 升级到 explain-error.js
+    // —— 后者覆盖协议错误码（17 个）+ HTTP 状态 + 握手超时等，不只是 5 类网络错误。
+    //
+    // ⚠ 结构化保存：面板要显示"最后尝试时间 + 人话 + 原始错误"三件套，
+    // 只存字符串的话面板只能原样打印。
+    const explained = explainError(err, { isHub: false, context: '连接主机' })
+    lastErrorDetail = {
+      at: Date.now(),
+      title: explained.title,
+      detail: explained.detail,
+      hint: explained.hint,
+      raw: explained.raw,
+      code: typeof err?.code === 'string' ? err.code : '',
+    }
+    logger.warn(`连接问题：${formatExplained(explained)}`, { nodeId, error: lastError })
   })
   // P2-11：hub 身份验证状态。'pending' 期间（relay 宽限窗口内）task/start 会被
   // 上面的 guard 拒绝；direct 模式在 welcome 时就已决出，宽限窗口实际只作用于
@@ -1197,6 +1227,9 @@ function startWorker(ctx, config) {
       },
       reconcile,
       lastError: lastError || null,
+      // 结构化的人话错误（面板据此显示"最后尝试 + 原因 + 下一步"）。
+      // 旧版副机没有这个字段 → 面板按 null 处理，退回只显示 lastError。
+      lastErrorDetail: lastErrorDetail || null,
       updatedAt: Date.now(),
     }
   }

package/package.json

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

package/scripts/check-doc-drift.mjs

@@ -1177,6 +1177,72 @@ check('65', 'eslint 严格档：lint script + 配置文件 + CI job 三件套齐
     'lib/listen-server.js（拒 0.0.0.0 + Tailscale 优先）+ hub/index.js（测试环境跳过）')
 }
 
+/* ── 88~90. 用户体验五项（2026-10-20）──
+ *
+ * 实测用户反馈："出了问题不知道原因"。五个断层：
+ *   ① 副机连不上时主机只显示「0 在线」，没有原因
+ *   ② 体检能查出来，但修法要手抄 YAML
+ *   ③ 首次使用不知道从哪开始
+ *   ④ 原始错误（ECONNREFUSED / 401 / timeout after 40000ms）直接抛给用户
+ *   ⑤ 长任务只能看到"运行中"，不知道在干什么
+ *
+ * 这三条断言钉住"每条都有对应实现"，防止后续重构把它们悄悄拿掉。
+ */
+{
+  const explainSrc = read('lib/explain-error.js')
+  const regSrc = read('lib/hub/node-registry.js')
+  const clientSrc6 = read('lib/client.js')
+  const uiSrc5 = read('lib/hub/ui-routes.js')
+
+  check('88', '体验④：统一错误翻译层覆盖 errno + 协议码 + HTTP + 文案特征',
+    /export function explainError/.test(explainSrc)
+    // errno 分支
+    && /ECONNREFUSED/.test(explainSrc)
+    && /ETIMEDOUT/.test(explainSrc)
+    && /EADDRINUSE/.test(explainSrc)
+    // 协议码（用 ERROR_CODE 常量，不写死字符串）
+    && /ERROR_CODE\.UNAUTHORIZED/.test(explainSrc)
+    && /ERROR_CODE\.PROTOCOL_MISMATCH/.test(explainSrc)
+    // HTTP 状态
+    && /case 401:/.test(explainSrc)
+    && /case 404:/.test(explainSrc)
+    // 文案特征
+    && /handshake timeout/.test(explainSrc)
+    // 每条都有 hint（下一步做什么）
+    && /hint:/.test(explainSrc),
+    'lib/explain-error.js（errno + 17 个协议码 + HTTP + 文案特征，每条带 hint）')
+
+  check('89', '体验①：连接尝试历史（记录 + 面板空态诊断）',
+    // 注册表记录每次尝试
+    /noteConnectionAttempt/.test(regSrc)
+    && /connectionLog/.test(regSrc)
+    && /connectionReport/.test(regSrc)
+    // 拒绝点与成功点都要记
+    && /noteConnectionAttempt/.test(read('lib/hub/registry-handshake.js'))
+    // 路由透出
+    && /connection: connReport/.test(uiSrc5)
+    // 面板渲染诊断（区分"从没连过"与"连过又断"）
+    && /connDiag/.test(clientSrc6)
+    && /everConnected/.test(clientSrc6),
+    'node-registry.js + registry-handshake.js + ui-routes.js + client.js')
+
+  check('90', '体验②③⑤：复制修法按钮 + 编号步骤 + 任务进度摘要',
+    // ② 复制修法
+    /复制修法/.test(clientSrc6)
+    && /copyText\(it\.fix\)/.test(clientSrc6)
+    // ③ 编号步骤（hub 侧 1-4 步）
+    && /'重启 DSH'/.test(clientSrc6)
+    && /'生成配对码'/.test(clientSrc6)
+    && /'在副机上粘贴'/.test(clientSrc6)
+    && /'等它连上'/.test(clientSrc6)
+    // ③ 角色选择提示
+    && /你现在用的这台/.test(clientSrc6)
+    // ⑤ 任务行进度摘要
+    && /progressLine/.test(clientSrc6)
+    && /最近：/.test(clientSrc6),
+    'lib/client.js（复制按钮 + 编号步骤 + 角色提示 + 任务进度摘要）')
+}
+
 /* ── 输出 ── */
 const failed = results.filter((r) => !r.ok)
 if (process.argv.includes('--json')) {