dsh-remote-agent 0.9.4 → 0.9.6

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/index.js

@@ -138,6 +138,31 @@ async function applyWorkerBranch(ctx, config, log) {
   }
 }
 
+/**
+ * 每个"注册宿主"上当前这一代的清理函数。
+ *
+ * 键选 **`ctx.webServer` 服务实例**，不是 `ctx`：
+ * 撞车的是**宿主的路由表**（`webServer.upgrades` 这张 Map）。同一个 ctx 当然
+ * 共用同一张表，但 DSH 热重载时也可能给每代一个新的子 ctx —— 那时按 ctx 记
+ * 就会漏掉，照样撞车。按服务实例记才对应"真正会冲突的那个东西"。
+ *
+ * 读不到 `ctx.webServer`（副机 profile 的 `inject: []` 一读就抛）时退回 ctx，
+ * 这条兜底只是让字典有键，不影响正确性。
+ *
+ * 用 WeakMap：既不阻止 GC，也不会把多个 profile / 多个 host 实例串在一起。
+ */
+const GENERATIONS = new WeakMap()
+
+/** 取"注册宿主"作为字典键。读服务可能抛（无 inject），所以必须 try。 */
+function generationKey(ctx) {
+  try {
+    const ws = ctx && ctx.webServer
+    return ws !== undefined && ws !== null ? ws : ctx
+  } catch {
+    return ctx
+  }
+}
+
 /**
  * DSH 插件入口。
  * @param {object} ctx Cordis 上下文
@@ -188,6 +213,64 @@ export function apply(ctx, config = {}) {
   }
   const handles = { role, hub: undefined, worker: undefined, unconfigured: unconfigured === true }
 
+  // ══════════════════════════════════════════════════════════════════════════
+  // 可重入：同一个 ctx 上只允许存在**一代**注册（0.9.5 修 duplicate 激活失败）
+  // ══════════════════════════════════════════════════════════════════════════
+  //
+  // 0.9.4 装上后 DSH 报：
+  //
+  //     webserver: duplicate upgrade route "/api/remote-agent/node"
+  //     1 entry did not activate remote-agent (dsh-remote-agent)
+  //
+  // 根因不是"注册了两次"写错，而是**我们的注册不可回收**：
+  //
+  //   · DSH 的 `webServer.registerUpgrade(path)` 是**按 path 查表**的，
+  //     同路径第二次注册直接抛（这是它的组合级契约，合理）：
+  //       if (this.upgrades.has(route.path)) throw new Error('webserver: duplicate upgrade route ...')
+  //   · 我们的注册全部收集在 `__disposers` 里、由 `applyHub()` 的返回值
+  //     `disposeAll` 交给调用方保管 —— 但 **DSH 不认识这个返回值**，
+  //     热重载/安装后 reload 时它只会重新 `apply`，不会回头调我们的 disposer。
+  //   · 于是第二代在第一代的残留上注册 → 撞车 → 整个 entry 激活失败。
+  //
+  // 为什么以前没暴露：只有"同一个 ctx 上重新 apply"才触发。DSH 在
+  // 插件安装/升级后会热重载，这正是用户装 0.9.4 时踩到的那一步。
+  //
+  // 修法：**不指望宿主帮我们清理**。按 ctx 记住上一代的 dispose，重新
+  // apply 时先自己摘干净再装。这样无论宿主是否调用 disposer，都不会重复注册。
+  const genKey = generationKey(ctx)
+  const prevDispose = GENERATIONS.get(genKey)
+  if (typeof prevDispose === 'function') {
+    try {
+      prevDispose()
+      log('info', 're-apply on the same host: previous generation disposed first')
+    } catch (err) {
+      log('warn', 'previous generation dispose failed (continuing)', {
+        error: String(err?.message ?? err),
+      })
+    }
+  }
+
+  let released = false
+  const dispose = () => {
+    if (released) return
+    released = true
+    // 只摘自己：新一代可能已经顶替了这一格，别把它的注册也拆了
+    if (GENERATIONS.get(genKey) === dispose) GENERATIONS.delete(genKey)
+    // 顺序：hub 的路由/监听 → setup 路由 → worker 拨号。
+    // 每一步独立兜底：一个失败不能让后面的漏摘（否则又变成"摘一半"）。
+    try { handles.hub?.disposeAll?.() } catch (err) {
+      log('warn', 'hub dispose failed', { error: String(err?.message ?? err) })
+    }
+    if (Array.isArray(handles.setup)) {
+      for (const d of handles.setup) {
+        try { if (typeof d === 'function') d() } catch { /* 已摘 */ }
+      }
+    }
+    try { if (typeof handles.worker === 'function') handles.worker() } catch { /* 已摘 */ }
+  }
+  GENERATIONS.set(genKey, dispose)
+  handles.dispose = dispose
+
   // ── 未配置：什么都不注册 ────────────────────────────────────────────────
   //
   // 为什么要有这个分支：首次安装时**插件无法知道这台机器是主机还是副机** ——
@@ -252,6 +335,12 @@ export function apply(ctx, config = {}) {
     // 动态 import 是异步的；不 await —— apply 本身是同步契约。
     // 失败已在 applyWorkerBranch 内部记日志，不让 host 因副机缺件而起不来。
     void applyWorkerBranch(ctx, config, log).then((h) => {
+      // 竞态：这一代已经被 dispose（热重载/卸载）了，把刚挂上的 worker 立刻摘掉。
+      // 否则它会留在后台继续拨号 —— 一份回收不掉的僵尸连接。
+      if (released) {
+        try { if (typeof h === 'function') h() } catch { /* 已摘 */ }
+        return
+      }
       handles.worker = h
     })
   }

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.4",
+  "version": "0.9.6",
   "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')) {