dsh-remote-agent 0.9.1 → 0.9.3

package/lib/instance-config.js

@@ -0,0 +1,207 @@
+/**
+ * 独立配置文件（2026-10-18，解决"配置被 DSH 重写冲掉"的根因）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 为什么需要它
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 实测事故（2026-10-18）：
+ *
+ *   01:44  cordis.patch.yml = 3962B / 15 条（含我们的 role + webserver）
+ *   12:05  cordis.patch.yml = 696B  /  4 条（**我们的段整段消失**）
+ *
+ * 12:05 前后用户在 DSH 里**卸载重装了插件**，同时 pnpm-lock.yaml 被更新。
+ * 结论：**DSH 的插件管理器在改动依赖时会重写 `cordis.patch.yml`，只保留它
+ * 自己管理的条目** —— 手工写的段会被冲掉。
+ *
+ * 这正是"每次设置完重启又回到引导页"的真正根因（不是版本旧、不是写错 profile）：
+ *
+ *   用户选角色 → 写入 cordis.patch.yml → 某次插件操作 → 我们的段被冲掉
+ *   → 重启 → role 消失 → 面板又显示引导
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 方案：配置分两层（本文件 = 不会被冲掉的那层）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ *   · **第 1 层**：`cordis.patch.yml` 里的 `- id: remote-agent` 行
+ *     —— 只负责"让 loader 加载这个插件"，内容可以极简（甚至只有 id + name）
+ *   · **第 2 层**：`<stateDir>/instance.json`（本文件管的这个）
+ *     —— 存 role / hubUrl / roots 等**真正的配置**
+ *
+ * loader 传进来的 config 与这里的值**合并**，后者在关键字段上**优先**
+ * （因为它是用户明确设置过、且不会被外力冲掉的）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 安全与边界
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ *   · 文件权限 0600（可能含 token）
+ *   · 原子写（tmp → rename），与 templates.js 同一套做法
+ *   · **绝不抛**：读失败/损坏时返回 null，让调用方退回 loader config
+ *     （配置读不出来不该让 DSH 起不来）
+ *   · 只存**白名单字段**，不存任意用户输入（防配置注入）
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/** 独立配置文件名（放在 stateDir 下）。 */
+export const INSTANCE_FILE_NAME = 'instance.json'
+
+/**
+ * 允许持久化的字段白名单。
+ *
+ * 为什么不直接存整个 config：config 里可能有 DSH 注入的东西（未知字段会
+ * 被 schemastery passthrough 保留），把它们写回磁盘等于把 loader 的中间态
+ * 固化下来。只存我们**真正需要跨重启保留**的。
+ */
+const PERSISTED_KEYS = Object.freeze([
+  'role',
+  'nodeId',
+  'transportMode',
+  'hubUrl',
+  'relayUrl',
+  'roots',
+  'nodeToken',
+  'uiPullRoot',
+  'agentMode',
+  'pair',
+])
+
+/**
+ * 解析 stateDir（与 lib/node/index.js 的 resolveStateDir 同口径）。
+ * @param {object} [config]
+ * @returns {string}
+ */
+export function resolveStateDir(config) {
+  const c = config && typeof config === 'object' ? config : {}
+  const explicit = typeof c.stateDir === 'string' ? c.stateDir.trim() : ''
+  if (explicit !== '') {
+    try {
+      return path.resolve(explicit)
+    } catch {
+      /* 落到默认 */
+    }
+  }
+  try {
+    return path.join(os.homedir(), '.dsh-remote-agent')
+  } catch {
+    return path.join(os.tmpdir(), '.dsh-remote-agent')
+  }
+}
+
+/** 独立配置文件的绝对路径。 */
+export function instanceFilePath(config) {
+  return path.join(resolveStateDir(config), INSTANCE_FILE_NAME)
+}
+
+/**
+ * 读独立配置。
+ *
+ * @param {object} [config] 用于解析 stateDir
+ * @returns {object|null} 读不到/损坏时返回 null（**不抛**）
+ */
+export function readInstanceConfig(config) {
+  const file = instanceFilePath(config)
+  let text
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch {
+    // ENOENT = 还没写过，是最常见的正常情况
+    return null
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    // 损坏：返回 null 让调用方退回 loader config（不让 DSH 起不来）
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+  // 字段级清洗（只取白名单，且去掉明显非法值）
+  const out = {}
+  for (const k of PERSISTED_KEYS) {
+    if (!(k in parsed)) continue
+    const v = parsed[k]
+    if (v === null || v === undefined) continue
+    // roots 是数组，单独清洗
+    if (k === 'roots') {
+      if (Array.isArray(v)) {
+        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
+        if (arr.length > 0) out.roots = arr
+      }
+      continue
+    }
+    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
+  }
+  return Object.keys(out).length > 0 ? out : null
+}
+
+/**
+ * 写独立配置（原子写 + 0600）。
+ *
+ * @param {object} values 要写的字段（按白名单过滤）
+ * @param {object} [config] 用于解析 stateDir
+ * @returns {{ok:boolean, file:string, error?:string}}
+ */
+export function writeInstanceConfig(values, config) {
+  const dir = resolveStateDir(config)
+  const file = path.join(dir, INSTANCE_FILE_NAME)
+  const src = values && typeof values === 'object' ? values : {}
+  const out = {}
+  for (const k of PERSISTED_KEYS) {
+    if (!(k in src)) continue
+    const v = src[k]
+    if (v === null || v === undefined) continue
+    if (k === 'roots') {
+      if (Array.isArray(v)) {
+        const arr = v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim())
+        if (arr.length > 0) out.roots = arr
+      }
+      continue
+    }
+    if (typeof v === 'string' && v.trim() !== '') out[k] = v.trim()
+  }
+
+  const tmp = `${file}.tmp-${process.pid}-${Date.now().toString(36)}`
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(tmp, `${JSON.stringify(out, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+    fs.renameSync(tmp, file)
+    return { ok: true, file }
+  } catch (err) {
+    try {
+      fs.rmSync(tmp, { force: true })
+    } catch {
+      /* 清理失败不掩盖原始错误 */
+    }
+    return { ok: false, file, error: String(err?.message ?? err) }
+  }
+}
+
+/**
+ * 把独立配置**合并进** loader 传进来的 config。
+ *
+ * ── 优先级（关键设计）──────────────────────────────────────────────────
+ *
+ * **独立配置优先** —— 因为：
+ *   · 它是用户通过面板明确设置过的值
+ *   · 它不会被 DSH 重写冲掉
+ *   · loader config 在"被冲掉"之后只剩包内默认（role: auto），
+ *     那正是"重启回引导页"的成因
+ *
+ * 例外：如果独立配置里**没有**某个字段，就用 loader config 的值。
+ *
+ * @param {object} loaderConfig
+ * @param {object} [opts]
+ * @param {boolean} [opts.overlay] 读到的独立配置（避免重复读盘）
+ * @returns {{config:object, source:object|null}}
+ */
+export function mergeInstanceConfig(loaderConfig, { overlay } = {}) {
+  const base = loaderConfig && typeof loaderConfig === 'object' ? loaderConfig : {}
+  let saved = overlay
+  if (saved === undefined) saved = readInstanceConfig(base)
+  if (!saved) return { config: base, source: null }
+  return { config: { ...base, ...saved }, source: saved }
+}

package/lib/listen-server.js

@@ -0,0 +1,262 @@
+/**
+ * 独立监听端口（2026-10-18，解决"副机永远连不上"的架构级问题）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 为什么不再用 ctx.webServer
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 原实现把副机拨入端点注册在 DSH 的 `ctx.webServer` 上：
+ *
+ *     ctx.webServer.registerUpgrade({ path: '/api/remote-agent/node', handler })
+ *
+ * 于是副机必须能访问 **DSH 的 webserver 端口**。而那个端口的绑定地址来自
+ * DSH 自己的配置，带来两个无法绕开的死结：
+ *
+ *   1. **DSH 每次启动都重写 `<profile>/cordis.patch.yml`**（实测：写进去的
+ *      `webserver` 段在下一次启动时被删掉，只留 3 个 `ui-*` 条目）→ 绑回
+ *      `127.0.0.1` → 副机连不上。
+ *   2. `webServer` 服务**激活即 listen**，没有 rebind 方法 → 插件运行时改不了。
+ *
+ * 而且新版 `dsh-host-webserver` 硬拒绝 `0.0.0.0`（会直接让 DSH 启动崩溃）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 现在的做法：插件自己开一个端口
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 用 `node:http` 起一个独立的 server，自己处理 WebSocket 升级
+ * （复用 `lib/ws.js` 的 `acceptUpgrade` —— 和 DSH 内部用的是同一套底层实现）。
+ *
+ * 好处：
+ *   · **完全不依赖 DSH 的 webserver 配置**，DSH 怎么重写 patch 都不影响
+ *   · host/port 由插件自己的配置决定，可以持久化到 instance.json
+ *   · 不碰 DSH 的任何文件
+ *
+ * 代价：
+ *   · 多一个监听端口（默认 19387）
+ *   · 需要用户/配置告诉它绑哪个具体 IP（新版规则不允许 0.0.0.0，这本身是好事：
+ *     只绑用户指定的那张网卡，暴露面最小）
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 绑定地址怎么定（关键设计）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 无法绑 `0.0.0.0`（与新版 DSH 同一考量：通配地址把服务暴露到所有网卡）。
+ * 所以按以下优先级选一个**具体 IP**：
+ *
+ *   1. 配置里的 `listenHost`（用户显式指定，最高优先）
+ *   2. **Tailscale IP**（100.64.0.0/10 段）—— 本插件的目标场景就是跨机，
+ *      Tailscale 地址固定不变、跨网可达，是最合理的选择
+ *   3. 第一个私网 IPv4（192.168/10./172.16-31）
+ *   4. `127.0.0.1`（兜底：至少本机能连，同机 both 模式可用）
+ *
+ * **自动选 IP 是刻意的**：不让用户为了一个"该绑哪张网卡"去查 ipconfig。
+ */
+
+import http from 'node:http'
+import os from 'node:os'
+
+import { acceptUpgrade } from './ws.js'
+
+/** 默认端口：与历史行为一致（文档、配对码、用户既有配置都指向它）。 */
+export const DEFAULT_LISTEN_PORT = 19387
+
+/** Tailscale 的 CGNAT 段（100.64.0.0/10）。 */
+function isTailscaleIp(ip) {
+  if (typeof ip !== 'string') return false
+  const m = /^100\.(\d+)\./.exec(ip)
+  if (!m) return false
+  const second = Number(m[1])
+  // 100.64.0.0/10 → 第二段 64..127
+  return second >= 64 && second <= 127
+}
+
+/** 私网段。 */
+function isPrivateIp(ip) {
+  if (typeof ip !== 'string') return false
+  return (
+    ip.startsWith('192.168.') ||
+    ip.startsWith('10.') ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(ip)
+  )
+}
+
+/**
+ * 列出本机所有非内网回环的 IPv4（按优先级排序）。
+ *
+ * @returns {Array<{address:string, family:string, iface:string, score:number}>}
+ */
+export function listCandidateAddresses() {
+  const out = []
+  let ifaces
+  try {
+    ifaces = os.networkInterfaces()
+  } catch {
+    return out
+  }
+  for (const [iface, list] of Object.entries(ifaces)) {
+    if (!Array.isArray(list)) continue
+    for (const info of list) {
+      if (!info || info.internal === true) continue
+      const family = info.family === 'IPv4' || info.family === 4 ? 'IPv4' : String(info.family)
+      if (family !== 'IPv4') continue
+      const address = typeof info.address === 'string' ? info.address : ''
+      if (address === '' || address.startsWith('169.254.')) continue // APIPA
+      // 优先级：Tailscale(0) > 私网(1) > 其它(2)
+      const score = isTailscaleIp(address) ? 0 : isPrivateIp(address) ? 1 : 2
+      out.push({ address, family, iface, score })
+    }
+  }
+  out.sort((a, b) => a.score - b.score)
+  return out
+}
+
+/**
+ * 决定监听地址。
+ *
+ * @param {object} [o]
+ * @param {string} [o.listenHost] 用户显式配置的地址
+ * @param {string[]} [o.candidates] 覆盖候选列表（测试用）
+ * @returns {{host:string, source:string, candidates:Array}}
+ */
+export function resolveListenHost({ listenHost, candidates } = {}) {
+  const list = Array.isArray(candidates) ? candidates : listCandidateAddresses()
+
+  // 1. 用户显式指定（且不是通配地址 —— 新版规则不允许）
+  if (typeof listenHost === 'string') {
+    const h = listenHost.trim()
+    if (h !== '' && h !== '0.0.0.0' && h !== '::' && h !== '[::]') {
+      return { host: h, source: 'config', candidates: list }
+    }
+  }
+
+  // 2. Tailscale IP
+  const ts = list.find((x) => isTailscaleIp(x.address))
+  if (ts) return { host: ts.address, source: 'tailscale', candidates: list }
+
+  // 3. 私网 IP
+  const priv = list.find((x) => isPrivateIp(x.address))
+  if (priv) return { host: priv.address, source: 'private', candidates: list }
+
+  // 4. 任意非回环
+  if (list.length > 0) return { host: list[0].address, source: 'any', candidates: list }
+
+  // 5. 兜底：本机回环（同机 both 模式仍可用）
+  return { host: '127.0.0.1', source: 'loopback', candidates: list }
+}
+
+/**
+ * 启动一个只服务本插件 WS 端点的小 HTTP server。
+ *
+ * 只做两件事：
+ *   · `GET <healthPath>` → 200 JSON（运维自检用，不泄露敏感信息）
+ *   · `Upgrade: websocket` → 交给 `onUpgrade`（副机拨入）
+ *
+ * 其它路径一律 404 —— 这不是通用 web server，只承载节点端点。
+ *
+ * @param {object} o
+ * @param {string} o.host 绑定的具体 IP
+ * @param {number} o.port 端口（0 = 随机）
+ * @param {string} o.path WS 升级路径（必须精确匹配）
+ * @param {(conn:import('./ws.js').WSConnection, req:import('node:http').IncomingMessage)=>void} o.onUpgrade
+ * @param {string} [o.healthPath] 健康检查路径
+ * @param {object} [o.healthBody] 健康检查返回体
+ * @param {(level:string,msg:string,extra?:object)=>void} [o.log]
+ * @returns {Promise<{server:import('node:http').Server, host:string, port:number, close:()=>Promise<void>}>}
+ */
+export function startListenServer({
+  host,
+  port = DEFAULT_LISTEN_PORT,
+  path: upgradePath,
+  onUpgrade,
+  healthPath = '/healthz',
+  healthBody = { ok: true },
+  log = () => {},
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const sockets = new Set()
+
+    const server = http.createServer((req, res) => {
+      // 健康检查：给运维/体检一个"端口真的活着"的判据
+      try {
+        const url = new URL(req.url || '/', 'http://localhost')
+        if (req.method === 'GET' && url.pathname === healthPath) {
+          res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+          res.end(JSON.stringify(healthBody))
+          return
+        }
+      } catch {
+        /* URL 解析失败：落到 404 */
+      }
+      res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })
+      res.end('not found\n')
+    })
+
+    // 追踪连接，close 时能强制断干净（否则旧连接会拖住 server.close）
+    server.on('connection', (socket) => {
+      sockets.add(socket)
+      socket.on('close', () => sockets.delete(socket))
+    })
+
+    server.on('upgrade', (req, socket, head) => {
+      let pathname
+      try {
+        pathname = new URL(req.url || '/', 'http://localhost').pathname
+      } catch {
+        socket.destroy()
+        return
+      }
+      // ⚠ 路径必须**精确匹配**：这个 server 只承载节点端点，
+      // 不开任何"顺手兼容一下"的口子（越宽的攻击面越难守）。
+      if (pathname !== upgradePath) {
+        socket.destroy()
+        return
+      }
+      const conn = acceptUpgrade(req, socket, head)
+      if (!conn) return
+      try {
+        onUpgrade(conn, req)
+      } catch (err) {
+        log('warn', 'upgrade handler threw', { error: String(err?.message ?? err) })
+        try {
+          conn.close(1011, 'internal error')
+        } catch {
+          /* 已关 */
+        }
+      }
+    })
+
+    server.on('error', (err) => {
+      // listen 失败（端口占用 / 地址不可用）要**明确报出来** ——
+      // 静默失败会让"副机连不上"变成又一个无头案。
+      reject(err)
+    })
+
+    server.listen(port, host, () => {
+      const addr = server.address()
+      const actualPort = addr && typeof addr === 'object' ? addr.port : port
+      log('info', 'node endpoint listening', { host, port: actualPort, path: upgradePath })
+
+      const close = () => new Promise((done) => {
+        try {
+          server.close(() => done())
+        } catch {
+          done()
+        }
+        // 强制断开存量连接：server.close 只是"停止接受新连接"，
+        // 已有 WS 连接会一直挂着，插件卸载时不能留悬挂句柄。
+        for (const s of sockets) {
+          try {
+            s.destroy()
+          } catch {
+            /* 已关 */
+          }
+        }
+        sockets.clear()
+        // 兜底超时：某些平台 close 回调可能不触发
+        setTimeout(done, 2000).unref?.()
+      })
+
+      resolve({ server, host, port: actualPort, close })
+    })
+  })
+}

package/lib/setup-routes.js

@@ -35,6 +35,9 @@ import { writePatchBlock } from './setup.js'
 // 角色解析必须**只有一份实现** —— 面板说"未配置"而插件实际在跑 hub，
 // 是最难排查的撕裂（v0.7.0 踩过）。所以这里直接复用 lib/index.js 的解析器。
 import { resolveRoleDetail } from './index.js'
+// 配置分层（2026-10-18）：DSH 插件管理器会重写 cordis.patch.yml 并冲掉手工段，
+// 所以每次写配置时也在 <stateDir>/instance.json 存一份（插件加载时合并回来）。
+import { writeInstanceConfig, readInstanceConfig } from './instance-config.js'
 
 /** 引导路由的前缀。与 hub 的 `/api/remote-agent/ui` 分开 —— 未配置时后者不存在。 */
 export const SETUP_API_PREFIX = '/api/remote-agent/setup'
@@ -216,12 +219,28 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
     // `configured` 的语义是"用户已经做过选择，不需要引导"。
     // auto 也算已选择：它是个明确的工作模式（按 hubUrl 推断），不是"还没配"。
     const configured = role === 'auto' || detail.unconfigured !== true
+
+    // ── 独立配置状态（2026-10-18）──────────────────────────────────────
+    //
+    // 报告 `<stateDir>/instance.json` 里存了什么。这不是给用户看的细节，
+    // 而是排查"配置被 DSH 重写冲掉"这个坑的关键线索：
+    //   · instance 有值 = 配置抗住了重写（重启后 apply() 会合并回来）
+    //   · instance 为 null 但 patch 有值 = 只靠 patch 那层，下次重写会丢
+    const saved = readInstanceConfig(config)
     writeJson(res, 200, {
       ok: true,
       configured,
       // 推断结果（面板据此显示"当前生效角色"）—— auto 时它是有值的
       effectiveRole: detail.role,
       inferred: typeof detail.inferred === 'string' ? detail.inferred : '',
+      // 配置持久化的两层状态
+      persist: {
+        // DSH 会重写 cordis.patch.yml（实测会把我们的段整段冲掉）
+        patchFile: currentPatchFile(),
+        // 这一层 DSH 冲不掉，是"重启后配置还在"的真正保障
+        instanceFile: saved !== null,
+        instanceRole: saved && typeof saved.role === 'string' ? saved.role : null,
+      },
       // 回显当前配置里已有的值，方便用户"改一个字段"而不是从头填
       current: {
         role: typeof config.role === 'string' ? role : '',
@@ -342,12 +361,41 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
       })
     }
     log('info', 'setup applied', { role, file: result.file, mode: result.mode, warnings: applyWarnings })
+
+    // ── 同时写独立配置（2026-10-18，方案 B：防被 DSH 重写冲掉）──────────
+    //
+    // 事故：用户在 DSH 里卸载重装插件后，`cordis.patch.yml` 被重写成只剩
+    // 4 条 —— 我们的 role + webserver 整段消失，重启后又回引导页。
+    //
+    // 所以每次 setup 写入成功后，把**同样的值**再存一份到
+    // `<stateDir>/instance.json`。插件 `apply()` 时会把它合并回来
+    // （独立配置优先）。这样 DSH 怎么重写 patch 文件都不影响角色配置。
+    //
+    // 失败不阻塞：独立配置写不进去时，patch 文件那层仍然生效（只是不抗冲掉）。
+    const persisted = writeInstanceConfig({
+      role,
+      nodeId: str(body.nodeId),
+      transportMode: str(body.transportMode) || undefined,
+      hubUrl: str(body.hubUrl) || undefined,
+      relayUrl: str(body.relayUrl) || undefined,
+      roots,
+    })
+    if (persisted.ok !== true) {
+      applyWarnings.push(`独立配置写入失败（${persisted.error}）—— 角色配置仍写进了 patch 文件，`
+        + '但下次 DSH 重写该文件时可能丢失，建议重启后到面板确认一次。')
+      log('warn', 'instance config write failed', { file: persisted.file, error: persisted.error })
+    } else {
+      log('info', 'instance config persisted', { file: persisted.file })
+    }
+
     writeJson(res, 200, {
       ok: true,
       role,
       file: result.file,
       backup: result.backup,
       mode: result.mode,
+      // 独立配置的落点（让用户/排查者知道配置存在哪两处）
+      instanceFile: persisted.ok === true ? persisted.file : null,
       // 非致命提示（自动建目录的结果等）—— 面板要显示，否则用户以为
       // "目录已就绪"而实际没有
       warnings: applyWarnings,

package/package.json

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