dsh-remote-agent 0.9.4 → 0.9.6

package/CHANGELOG.md

@@ -9,6 +9,196 @@
 
 ---
 
+## [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 报激活失败，插件显示"异常"。**
+>
+> ```
+> webserver: duplicate upgrade route "/api/remote-agent/node"
+> 1 entry did not activate remote-agent (dsh-remote-agent)
+> ```
+>
+> 0.9.4 在**全新启动**的场景是好的（我验证过单次 apply 注册一次），
+> 但**热重载会撞车** —— 而 DSH 在插件安装/升级后正是靠热重载生效的。
+
+### 🔴 根因：我们的注册不可回收，而宿主不会帮我们回收
+
+`webServer.registerUpgrade(path)` 在 DSH 里是**按 path 查表**的，同路径第二次
+注册直接抛（组合级契约，它这么做是对的）：
+
+```js
+registerUpgrade(route) {
+  if (this.upgrades.has(route.path)) throw new Error(`webserver: duplicate upgrade route "${route.path}"`)
+  this.upgrades.set(route.path, route)
+  return () => { this.upgrades.delete(route.path) }
+}
+```
+
+而本插件的注册全部收集在 `__disposers` 里，通过 `applyHub()` 的返回值
+（`disposeAll`）交给调用方保管 —— **但 DSH 不认识这个返回值**。热重载时它只
+重新 `apply`，不会回头调我们的 disposer。于是第二代的注册压在第一代的残留上：
+
+```
+第一代 apply → 注册 /api/remote-agent/node（表里有了）
+DSH 热重载 → 直接再 apply（不 dispose）
+第二代 apply → registerUpgrade(同一 path) → throw → 整个 entry 激活失败
+```
+
+0.9.3 及以前没暴露，是因为那时改完配置都靠"重启 DSH"（进程重来，表是新的）；
+0.9.4 是在插件管理页里安装/升级，走了热重载路径 —— 这是**场景差异，不是新引入的代码**。
+
+### 修复
+
+1. **apply 变成可重入**（`lib/index.js`）：按**注册宿主**（`ctx.webServer` 服务
+   实例，读不到时退回 ctx）记住"当前这一代"的 dispose；重新 apply 时先自己把
+   上一代摘干净再装。**不指望宿主帮我们清理** —— 这是唯一在各种宿主行为下都
+   成立的修法。
+2. **`disposeAll` 改成逆序**（`lib/hub/index.js`）：此前是正序跑的，会先拆运行时
+   （`registry.dispose()`）再拆工具，工具的 disposer 可能碰到已销毁的 registry。
+   现在与 cordis 的"逆序释放"语义一致。
+3. **独立监听加了 EADDRINUSE 有限重试**：重入时先 `close()` 旧监听、立刻用同一
+   端口重新 `listen`，在 Windows 上经常还拿不到端口（close 是异步的）。重试
+   4 次（200/400/600ms 退避），真被别的进程占用仍会如实报错。
+4. **`handles.dispose`**：apply 的返回值现在带一个顶层 `dispose()`，任何愿意调
+   它的宿主都能正确清理。
+
+### 为什么 CI 没拦住（第三次同类）
+
+仓库里所有测试桩都**比宿主宽松**：`hub-worker-e2e.test.js` 的 `makeCtx()` 里
+`register()` 是 `table.set()`（同名静默覆盖）、`registerUpgrade()` 只是再挂一个
+`server.on('upgrade')`。真宿主会抛，桩不会 —— **桩比宿主宽松 = 假绿灯**。
+
+新增 `test/webserver-contract.test.js`：照宿主源码造一个**重复即抛**的严格 ctx，
+钉住四条契约：
+
+- 单次 apply 只注册一条 upgrade 路由
+- **同一 ctx 重复 apply 不抛**（就是本次的事故回归）
+- apply → dispose → apply 可反复进行，且旧世代的 dispose 不得影响新世代
+- 重入后**独立监听仍能绑回同一端口**（热重载不能把端点变成永久不可用）
+
+### 升级须知
+
+- 装完请在插件页把开关**关一次再打开**（或重启 DSH），让热重载重新加载新代码。
+- 如果你之前点了「生成口令」，副机要用新口令重新配对。
+
+```
+packaging   4 项
+doc-drift   123/123
+diag:inject 11 项
+tests       987（985 pass / 0 fail / 2 skip）
+lint        干净
+```
+
 ## [0.9.4] - 2026-10-20
 
 > **0.9.3 审查的 19 项全部修完。** 0.9.3 把架构换对了（插件自己开 19387），

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** | 982 (980 pass / 2 skip) · 123 doc-drift assertions · eslint strict |
+| **Tests** | 987 (985 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,

package/README.md

@@ -30,12 +30,12 @@
 
 | | |
 |---|---|
-| **状态** | 0.9.4 —— 主机 + 副机端到端可用；`exec` 与 `agent` 双链路均已在两台真机上验证通过；CI 覆盖 Windows / macOS / Linux |
+| **状态** | 0.9.5 —— 主机 + 副机端到端可用；`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` |
-| **测试** | 982 项（980 pass / 2 skip）· 123 条文档漂移断言 · eslint 严格档 |
+| **测试** | 987 项（985 pass / 2 skip）· 123 条文档漂移断言 · eslint 严格档 |
 
 **Web 面板**（侧栏「远程同事」）：节点列表（含 CPU/内存徽章）、派发任务、
 任务状态、结果摘要、工作区变更、成品清单、日志尾巴、**环境体检**、

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,