dsh-napcat-keeper 2.7.3 → 2.8.1

package/lib/index.js

@@ -1,9 +1,33 @@
 /**
- * dsh-napcat-keeper —— NapCat 看门狗 v2.7.3（可发布通用版）
+ * dsh-napcat-keeper —— NapCat 看门狗 v2.8.1（可发布通用版）
  *
  * 解决的问题：DSH 是桌面应用，重启 DSH 时 NapCat(QQ 协议端) 不会跟着起来，
  * 于是 dsh-qq-bridge 一直轮询一个死端口，你在 QQ 里说的话就石沉大海。
  *
+ * v2.8.1：认得出两个共存插件，端口不用自己抄
+ *   - 读 dsh-onebot-qq 的配置（profile 的 package.json、cordis.patch.yml / cordis.yml），
+ *     得出「装没装 / 挂没挂 / 反向还是正向 / 监听哪个端口 / 令牌配没配」；
+ *     你填的端口不通、它确实挂着反向 WS 时自动跟随（companionFollow，默认开），
+ *     你填的端口一通就绝不插手；没挂进 profile 或它是正向模式则不跟，并说明为什么；
+ *   - 读 dsh-qq-bridge 的 ~/.dsh/qq-bridge-config.json，把它填的 NapCat 地址与本插件
+ *     看到的实际情况交叉比对，五种结论（没挂载 / 连了反向 WS 端口 / 端口对不上 /
+ *     总开关关着 / 试运行中）写进设置页「桥接插件」行与 napcat_status；只看配置，
+ *     不碰它的进程和文件；
+ *   - 两个插件共用一套 profileHits 挂载判定；napcat_status.companion 改成
+ *     { onebot, bridge }（2.8.0 那份单值结构没发出去，直接换掉）；
+ *   - 「跟随」那一行跟着探测结果走：dsh-onebot-qq 没装 / 没挂载就整行不画、值按关算，
+ *     挂进 profile 才出现且默认开；用户显式关过就一直关，升级重启不会掰回开；
+ *     设置页保存改成只发有变化的键，saveAndApply 也挡住未启用时的 companionFollow 落盘。
+ *
+ * v2.8.0：认得出反向 WebSocket（和 dsh-onebot-qq 共存）
+ *   - NapCat 走反向 WS 时端口是别人在听（dsh-onebot-qq 之类），HTTP 换来 401/426；
+ *     postOneBot 原先只看 body 不看状态码，于是把「端口在回话」当成「端口不通」
+ *     → 判卡死 → 杀掉重拉 → 无限循环；
+ *   - 现在 probe() 分出 http / reverse / auth / process / dead，反向模式下「在线」=
+ *     端口上有客户端连进来（Get-NetTCPConnection -RemotePort 数），进程在 + 端口有服务
+ *     就不杀；真等不来客户端也只温和重拉两次，之后给提示而不是继续杀；
+ *   - 新增 probeMode（auto / http / reverse / process）；拉起连续失败时宽限期按 2 的幂退避。
+ *
  * v2.7.3：设置页保存不再空转
  *   - 2.7.0 把配置文件收进 keeperDir 时只改了「读」，saveAndApply / clearPassword
  *     还在写 ~/.dsh/config.json，于是点保存 / 点「用这个」之后值立刻弹回原样；
@@ -138,7 +162,7 @@ import { homedir, tmpdir } from 'node:os'
 import path from 'node:path'
 
 export const name = 'napcat-keeper'
-export const version = '2.7.3'
+export const version = '2.8.1'
 
 /** tools 用来注册 napcat_* 工具；webServer 用来挂设置界面接口。拿不到也不至于把 DSH 拖崩。 */
 export const inject = ['tools', 'webServer']
@@ -171,6 +195,20 @@ const DEFAULTS = {
   onebotPort: 3000,
   /** OneBot access token，没有就留空 */
   accessToken: '',
+  /**
+   * 怎么判断「NapCat 在线」。
+   *   auto     先当 HTTP 接口问，问不通再看端口是不是反向 WebSocket（默认，两边都能用）
+   *   http     只认 HTTP OneBot 接口
+   *   reverse  只认反向 WebSocket：端口上有没有客户端连进来（配合 dsh-onebot-qq 这类反向 WS 服务）
+   *   process  只看进程在不在，不碰端口
+   */
+  probeMode: 'auto',
+  /**
+   * 跟随 dsh-onebot-qq：自己填的端口连不上、而机器上挂着的 dsh-onebot-qq 是反向 WS 模式时，
+   * 自动把探测指向它监听的那个端口（用户显式填的端口一旦通了就还是用用户的）。
+   * 默认开 —— 这正是「装了反向 WS 插件却一直判离线」那个坑的解药。
+   */
+  companionFollow: true,
   /** 只在这些路径下找 QQ/NapCat 进程；留空 = 由 shellDir 推导（上层目录） */
   procPathMatch: '',
   /** 复查间隔（秒） */
@@ -231,12 +269,16 @@ const STATE_KEY = Symbol.for('dsh.napcat-keeper.state')
 const state =
   globalThis[STATE_KEY] ||
   (globalThis[STATE_KEY] = {
-    phase: 'idle', // idle | online | launching | starting | need-scan | need-scan-giveup | offline
+    phase: 'idle', // idle | online | launching | starting | need-scan | need-scan-giveup | reverse-wait | reverse-giveup | need-token | port-busy | offline
     lastProbeAt: null,
     lastOnlineAt: 0,
     lastLaunchAt: 0,
     lastError: '',
     launchCount: 0,
+    /** 连续拉起几次都没等到上线：宽限期按 2 的幂放大，免得每 45 秒杀一次 */
+    launchFails: 0,
+    /** 反向 WS 模式下「温和重拉」的次数，用完就认命给提示，不再折腾进程 */
+    reverseRetries: 0,
     dedupeCount: 0,
     scanSince: 0,
     scanRetries: 0,
@@ -764,6 +806,10 @@ function normalizeConfig(cfg) {
   cfg.launchAccount = String(cfg.launchAccount || '').trim().replace(/\D/g, '')
   cfg.launchArgs = String(cfg.launchArgs || '').trim()
   cfg.accessToken = String(cfg.accessToken || '').trim()
+  cfg.probeMode = PROBE_MODES.has(String(cfg.probeMode || '').trim().toLowerCase())
+    ? String(cfg.probeMode).trim().toLowerCase()
+    : 'auto'
+  cfg.companionFollow = cfg.companionFollow !== false && cfg.companionFollow !== 'false'
   cfg.procPathMatch = String(cfg.procPathMatch || '').trim()
   cfg.taskName = String(cfg.taskName || '').trim()
   cfg.onebotPort = clampNum(cfg.onebotPort, 1, 65535, 3000)
@@ -792,8 +838,23 @@ function resolveConfig(raw) {
   // 老版本的东西摊在 ~/.dsh 根上，先搬进 dir 再读配置（否则读的是搬走前的那份）
   migrateLegacyFiles(dir)
   // 优先级：内置默认 < cordis 里的 config < 设置界面存下来的 json
-  const cfg = { ...DEFAULTS, ...(raw || {}), ...readConfigFile(dir) }
+  const inline = raw || {}
+  const stored = readConfigFile(dir)
+  // 用户（或本插件自己）显式写过 companionFollow 吗？写过就尊重它，没写过才轮到动态默认值
+  const followSet =
+    Object.prototype.hasOwnProperty.call(stored, 'companionFollow') ||
+    Object.prototype.hasOwnProperty.call(inline, 'companionFollow')
+  const cfg = { ...DEFAULTS, ...inline, ...stored }
   normalizeConfig(cfg)
+  // 跟随 dsh-onebot-qq：装了且挂进 profile（= 启用）才算数，可用时默认开；
+  // 没装或没启用直接按关算 —— 设置页也据此不渲染这一行。
+  // companionFollowWant 存「你自己想要的值」（显式关过就是 false，没写过就是默认 true），
+  // 真正的 cfg.companionFollow 由「可用吗」压一道闸；这样对面后来才挂上 / 又摘掉时，
+  // 不用重启也能算对，而且不会把显式关掉的选择弄丢。
+  cfg.companionFollowWant = followSet ? cfg.companionFollow !== false : true
+  const comp = detectCompanion()
+  cfg.companionReady = companionReady(comp)
+  cfg.companionFollow = cfg.companionReady ? cfg.companionFollowWant : false
   // v2.2.2：shellDir 不再自动探测/自动填，空着就等用户在设置页里扫盘选或者手填
   if (!cfg.launcherScript) cfg.launcherScript = detectLauncher(cfg.shellDir, cfg.launchAccount)
   if (!cfg.logPath) cfg.logPath = path.join(dir, 'keeper.log')
@@ -865,7 +926,14 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 /* OneBot                                                             */
 /* ------------------------------------------------------------------ */
 
-function postOneBot(cfg, action, payload, timeoutMs = 4000) {
+/**
+ * 发一个 OneBot HTTP 动作。
+ *
+ * 返回值里带上 HTTP 状态码：反向 WebSocket 模式下（比如 dsh-onebot-qq 占着这个端口）
+ * 对方根本不会回 OneBot 的 JSON，能拿到的唯一线索就是 401 / 426 这类状态码 ——
+ * 老版本把状态码丢了，于是一律当成「端口不通」，接着就是杀掉重拉，无限循环。
+ */
+function postOneBot(cfg, action, payload, timeoutMs = 4000, port = 0) {
   return new Promise((resolve) => {
     const body = JSON.stringify(payload || {})
     const headers = {
@@ -878,57 +946,677 @@ function postOneBot(cfg, action, payload, timeoutMs = 4000) {
       req = http.request(
         {
           host: '127.0.0.1',
-          port: cfg.onebotPort,
+          port: Number(port) || cfg.onebotPort,
           path: `/${action}`,
           method: 'POST',
           headers,
           timeout: timeoutMs,
         },
         (res) => {
+          const status = Number(res.statusCode) || 0
           let buf = ''
           res.setEncoding('utf8')
           res.on('data', (c) => {
             buf += c
           })
           res.on('end', () => {
+            const raw = String(buf).slice(0, 200)
+            let parsed = null
             try {
-              resolve(JSON.parse(buf))
-            } catch {
-              resolve({ retcode: -1, raw: String(buf).slice(0, 200) })
+              parsed = JSON.parse(buf)
+            } catch {}
+            if (parsed && typeof parsed === 'object') {
+              resolve({ ...parsed, status })
+              return
             }
+            resolve({ retcode: -1, status, raw })
           })
         },
       )
     } catch (error) {
-      return resolve({ retcode: -1, error: String((error && error.message) || error) })
+      return resolve({ retcode: -1, status: 0, error: String((error && error.message) || error) })
     }
     req.on('timeout', () => {
       try {
         req.destroy(new Error('timeout'))
       } catch {}
-      resolve({ retcode: -1, error: 'timeout' })
+      resolve({ retcode: -1, status: 0, error: 'timeout' })
     })
-    req.on('error', (error) => resolve({ retcode: -1, error: String((error && error.message) || error) }))
+    req.on('error', (error) =>
+      resolve({ retcode: -1, status: 0, error: String((error && error.message) || error) }),
+    )
     try {
       req.write(body)
       req.end()
     } catch (error) {
-      resolve({ retcode: -1, error: String((error && error.message) || error) })
+      resolve({ retcode: -1, status: 0, error: String((error && error.message) || error) })
     }
   })
 }
 
-async function probe(cfg) {
-  const login = await postOneBot(cfg, 'get_login_info')
+/* ------------------------------------------------------------------ */
+/* 和 dsh-onebot-qq 共存：认得出对面那个反向 WebSocket 服务              */
+/*                                                                     */
+/* 反向 WS 部署里端口是「别人」在听（最常见就是 dsh-onebot-qq），NapCat   */
+/* 反过来连进去。这种部署下用户得自己把两边的端口/令牌抄成一样，抄错就表现 */
+/* 成「永远离线 + 反复重启」。                                          */
+/* 那两样东西其实就在本机的 profile 里，读得出来：                        */
+/*   <DSH_HOME>/profiles/<profile>/package.json     装了没 / 挂进树没     */
+/*   <DSH_HOME>/profiles/<profile>/cordis.patch.yml  它自己的 config      */
+/* 读出来以后：用户自己填的端口优先，填的那个不通再跟随它的端口；令牌对不上 */
+/* 就直接说清楚。                                                        */
+/*                                                                     */
+/* 铁律：只读文件、只发 HTTP 探测。绝不对它做 WebSocket 握手 ——          */
+/* dsh-onebot-qq 是 last-wins，真握手会把 NapCat 那条连接顶掉。           */
+/* ------------------------------------------------------------------ */
+
+const COMPANION_PACKAGE = 'dsh-onebot-qq'
+/** 它在 cordis 树里的插件 id（patch 里 insert 的是这个，不是包名） */
+const COMPANION_ID = 'dsh-onebot'
+/** dsh-onebot-qq lib/index.js:67-77 那份 Config 的默认值；读不到配置就用它 */
+const COMPANION_DEFAULTS = {
+  mode: 'reverse',
+  host: '127.0.0.1',
+  port: 8643,
+  url: 'ws://127.0.0.1:3001',
+  accessToken: '',
+}
+
+const companionCache = { at: 0, value: null }
+
+/** 读 JSON，读不出来就 null（profile 里的文件可能正被编辑，不能崩） */
+function readJsonQuiet(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))
+    return parsed && typeof parsed === 'object' ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** YAML 标量：去引号、去行尾注释（` #` 之后才算注释，URL 里的 // 不算）、`!!js` 认不出就当空 */
+function yamlScalar(raw) {
+  let text = String(raw == null ? '' : raw).trim()
+  if (!text) return ''
+  if (text.startsWith('!!js')) return ''
+  const quoted = /^(['"])([\s\S]*)\1$/.exec(text)
+  if (quoted) return quoted[2]
+  const hash = text.search(/\s#/)
+  if (hash >= 0) text = text.slice(0, hash).trim()
+  if (text === '~' || text === 'null') return ''
+  // 纯整数当数字（端口这类），别的原样留着
+  if (/^-?\d+$/.test(text)) return Number(text)
+  return text
+}
+
+/** 行内 `{ a: 1, b: c }` → [[a,'1'],[b,'c']]（不处理嵌套，够用了） */
+function inlinePairs(text) {
+  const pairs = []
+  const body = String(text || '').trim().replace(/^\{/, '').replace(/\}$/, '')
+  if (!body) return pairs
+  for (const chunk of body.split(',')) {
+    const m = /^\s*([A-Za-z_][\w-]*)\s*:\s*([\s\S]*)$/.exec(chunk)
+    if (m) pairs.push([m[1], yamlScalar(m[2])])
+  }
+  return pairs
+}
+
+/**
+ * 从 cordis.patch.yml / cordis.yml 的文本里挖出 dsh-onebot 那一项的 config。
+ *
+ * 不引 YAML 库：这文件是我们自己读的，认不出的写法（`!!js` 表达式等）宁可当没有，
+ * 也不要把半个值当真配置拿去用。
+ */
+function parseCompanionConfig(text) {
+  const out = {}
+  const lines = String(text || '')
+    .replace(/^\uFEFF/, '')
+    .split(/\r?\n/)
+  const isEntryLine = (body) => /(^|[{,\s])id:\s*['"]?dsh-onebot['"]?(\s|,|}|$)/.test(body)
+  let inEntry = false
+  let entryIndent = 0
+  let configIndent = -1
+  for (const line of lines) {
+    if (!line.trim() || /^\s*#/.test(line)) continue
+    const indent = line.length - line.trimStart().length
+    if (/^\s*-/.test(line)) {
+      const body = line.replace(/^\s*-\s*/, '')
+      if (isEntryLine(body)) {
+        inEntry = true
+        entryIndent = indent
+        configIndent = -1
+        const cm = /config:\s*(\{[\s\S]*\})\s*$/.exec(body)
+        if (cm) {
+          for (const [k, v] of inlinePairs(cm[1])) if (v !== '') out[k] = v
+        }
+        continue
+      }
+      // 同级的下一条 insert 项：上一条结束了
+      if (indent <= entryIndent) {
+        inEntry = false
+        configIndent = -1
+      }
+      continue
+    }
+    if (!inEntry) continue
+    if (indent <= entryIndent) {
+      inEntry = false
+      configIndent = -1
+      continue
+    }
+    if (/^\s*config:\s*$/.test(line)) {
+      configIndent = indent
+      continue
+    }
+    const inline = /^\s*config:\s*(\{[\s\S]*\})\s*$/.exec(line)
+    if (inline) {
+      for (const [k, v] of inlinePairs(inline[1])) if (v !== '') out[k] = v
+      configIndent = -1
+      continue
+    }
+    if (configIndent >= 0 && indent > configIndent) {
+      const m = /^\s*([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line)
+      if (m) {
+        const value = yamlScalar(m[2])
+        if (value !== '') out[m[1]] = value
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * 扫一遍 `~/.dsh/profiles/*`，找出「装了这个包」的 profile。
+ *
+ * 两个共存插件（dsh-onebot-qq / dsh-qq-bridge）用的是同一套判断：
+ *   - 装了 = 它的 package.json 在 node_modules 里，或者写在 profile 的 dependencies 里；
+ *   - 挂了 = 出现在 `dsh.profile.bundles` 里，或者被 `cordis.patch.yml` / `cordis.yml`
+ *     单独 insert 过（认 `id: xxx`）。只装在 dependencies 里而没进 bundles 的，DSH 不会加载它，
+ *     端口/路由都不会起来 —— 这个区别很要紧，不能混成一句「已安装」。
+ *
+ * 正在跑的那个 profile（desktop）排最前：多 profile 并存时优先信它。
+ */
+function profileHits(pkgName, bundleId) {
+  const root = path.join(dshHome(), 'profiles')
+  let dirs = []
+  try {
+    dirs = readdirSync(root, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => path.join(root, d.name))
+  } catch {
+    dirs = []
+  }
+  const current = path.join(root, 'desktop')
+  dirs.sort((a, b) => (a === current ? -1 : b === current ? 1 : a.localeCompare(b)))
+
+  const idRe = new RegExp(`(^|[{,\\s])id:\\s*['"]?${bundleId}['"]?(\\s|,|}|$)`)
+  const hits = []
+  for (const dir of dirs) {
+    const pkg = readJsonQuiet(path.join(dir, 'package.json'))
+    const deps = (pkg && pkg.dependencies) || {}
+    const meta = readJsonQuiet(path.join(dir, 'node_modules', pkgName, 'package.json'))
+    if (!meta && !Object.prototype.hasOwnProperty.call(deps, pkgName)) continue
+
+    const bundles = (pkg && pkg.dsh && pkg.dsh.profile && pkg.dsh.profile.bundles) || []
+    const patches = []
+    for (const name of ['cordis.patch.yml', 'cordis.yml']) {
+      const file = path.join(dir, name)
+      let text = ''
+      try {
+        text = readFileSync(file, 'utf8')
+      } catch {
+        continue
+      }
+      if (text.includes(pkgName) || idRe.test(text)) patches.push({ name, text })
+    }
+    hits.push({
+      dir,
+      profile: path.basename(dir),
+      version: String((meta && meta.version) || deps[pkgName] || ''),
+      bundles,
+      patches,
+      mounted: bundles.includes(pkgName) || patches.length > 0,
+    })
+  }
+  return hits
+}
+
+/** 它装没装、挂没挂、自己配成什么样（20 秒缓存；改了 profile 也不用等太久） */
+function detectCompanion(options = {}) {
+  const force = Boolean(options && options.force)
+  const maxAgeMs = Number.isFinite(Number(options && options.maxAgeMs))
+    ? Math.max(0, Number(options.maxAgeMs))
+    : 20000
+  if (!force && companionCache.value && Date.now() - companionCache.at < maxAgeMs) {
+    return companionCache.value
+  }
+  const result = {
+    found: false,
+    packageVersion: '',
+    profile: '',
+    mounted: false,
+    mode: '',
+    host: '',
+    port: 0,
+    url: '',
+    /** 只有能读到明文时才有值；界面上永远不外发，只回「配没配、一致不」 */
+    token: '',
+    tokenKnown: false,
+    source: '',
+    candidates: [],
+  }
+  for (const hit of profileHits(COMPANION_PACKAGE, COMPANION_ID)) {
+    const patchConfig = {}
+    for (const p of hit.patches) Object.assign(patchConfig, parseCompanionConfig(p.text))
+
+    const cfg = { ...COMPANION_DEFAULTS, ...patchConfig }
+    const candidate = {
+      found: true,
+      packageVersion: hit.version,
+      profile: hit.dir,
+      mounted: hit.mounted,
+      mode: String(cfg.mode || '').toLowerCase() === 'forward' ? 'forward' : 'reverse',
+      host: String(cfg.host || '').trim() || COMPANION_DEFAULTS.host,
+      port: Number(cfg.port) || COMPANION_DEFAULTS.port,
+      url: String(cfg.url || '').trim() || COMPANION_DEFAULTS.url,
+      token: String(cfg.accessToken || ''),
+      tokenKnown: Object.prototype.hasOwnProperty.call(patchConfig, 'accessToken'),
+      source: Object.keys(patchConfig).length ? 'patch' : 'default',
+    }
+    result.candidates.push(candidate)
+    if (!result.found || (candidate.mounted && !result.mounted)) Object.assign(result, candidate)
+    if (candidate.mounted) break
+  }
+  companionCache.at = Date.now()
+  companionCache.value = result
+  return result
+}
+
+/**
+ * 「跟随 dsh-onebot-qq」能不能开：装了不算数，得真挂进 profile（bundles 或 cordis patch）。
+ * 只在 dependencies 里躺着的时候它根本不会起，跟着它去看端口只会白等。
+ * 两种入参都吃：detectCompanion() 的完整结果（带 found），以及 companionPublic() 的瘦身版（没有 found，只带 version/profile）。
+ */
+function companionReady(comp) {
+  if (!comp) return false
+  const found = Object.prototype.hasOwnProperty.call(comp, 'found')
+    ? Boolean(comp.found)
+    : Boolean(comp.version || comp.profile)
+  return found && Boolean(comp.mounted)
+}
+
+/** 给界面看的那部分（token / tokenKnown 之外的敏感信息一律不出这个函数） */
+function companionPublic(comp) {
+  if (!comp || !comp.found) return null
+  return {
+    version: comp.packageVersion,
+    profile: path.basename(String(comp.profile || '')),
+    mounted: Boolean(comp.mounted),
+    mode: comp.mode,
+    host: comp.host,
+    port: comp.port,
+    url: comp.url,
+    tokenKnown: Boolean(comp.tokenKnown),
+    source: comp.source,
+  }
+}
+
+/** 两边的 accessToken 一样吗？读不到对面的就返回 null（未知 ≠ 不一致） */
+function companionTokenMatch(cfg, comp) {
+  if (!comp || !comp.tokenKnown) return null
+  return String(cfg.accessToken || '') === String(comp.token || '')
+}
+
+/* ------------------------------------------------------------------ *
+ * 第二个共存插件：dsh-qq-bridge（把 NapCat 的消息接到 QQ 聊天里）
+ *
+ * 它和 dsh-onebot-qq 是两种东西：onebot 提供「接口」，qq-bridge 是「客户端」——
+ * 它拿 HTTP/WS 去连 NapCat，所以两边端口必须对上，对不上就静默不工作。
+ * 它的配置不在 profile 里，摊在 ~/.dsh/qq-bridge-config.json（中文键名）。
+ * ------------------------------------------------------------------ */
+
+const BRIDGE_PACKAGE = 'dsh-qq-bridge'
+const BRIDGE_ID = 'qq-bridge'
+const BRIDGE_DEFAULTS = { napcat: 'http://127.0.0.1:3000', enabled: false, dryRun: true }
+const bridgeCache = { at: 0, value: null }
+
+/** 从 OneBot 地址里抠端口（认不出就 0，不要瞎猜） */
+function urlPort(raw) {
+  try {
+    const u = new URL(String(raw || ''))
+    if (u.port) return Number(u.port)
+    return u.protocol === 'https:' ? 443 : 80
+  } catch {
+    return 0
+  }
+}
+
+/** 读它自己的配置文件；读不到就当「不知道」，别当成「没配」 */
+function readBridgeConfig() {
+  const file = path.join(dshHome(), 'qq-bridge-config.json')
+  const json = readJsonQuiet(file)
+  return { file, known: Boolean(json && typeof json === 'object'), cfg: json || null }
+}
+
+/** 它装没装、挂没挂、桥接指向哪个端口（20 秒缓存） */
+function detectBridge(options = {}) {
+  const force = Boolean(options && options.force)
+  const maxAgeMs = Number.isFinite(Number(options && options.maxAgeMs))
+    ? Math.max(0, Number(options.maxAgeMs))
+    : 20000
+  if (!force && bridgeCache.value && Date.now() - bridgeCache.at < maxAgeMs) return bridgeCache.value
+
+  const hits = profileHits(BRIDGE_PACKAGE, BRIDGE_ID)
+  const top = hits.find((h) => h.mounted) || hits[0] || null
+  const rc = readBridgeConfig()
+  const cfg = rc.cfg || {}
+  const napcatUrl = String(cfg.NapCat || '').trim() || BRIDGE_DEFAULTS.napcat
+
+  const result = {
+    found: Boolean(top),
+    packageVersion: String((top && top.version) || ''),
+    profile: String((top && top.profile) || ''),
+    mounted: Boolean(top && top.mounted),
+    configFile: rc.file,
+    configKnown: rc.known,
+    enabled: rc.known ? cfg.总开关 === true : BRIDGE_DEFAULTS.enabled,
+    dryRun: rc.known ? cfg.试运行 !== false : BRIDGE_DEFAULTS.dryRun,
+    napcatUrl,
+    napcatPort: urlPort(napcatUrl),
+    tokenKnown: rc.known ? String(cfg.令牌 || '').trim() !== '' : false,
+    bindings: rc.known && Array.isArray(cfg.绑定) ? cfg.绑定.length : 0,
+    candidates: hits.map((h) => ({ profile: h.profile, mounted: h.mounted, version: h.version })),
+  }
+  bridgeCache.at = Date.now()
+  bridgeCache.value = result
+  return result
+}
+
+/** 给界面/工具看的那部分（令牌只回「配没配」，不回来路不明的明文） */
+function bridgePublic(bridge) {
+  if (!bridge || !bridge.found) return null
+  return {
+    version: bridge.packageVersion,
+    profile: bridge.profile,
+    mounted: bridge.mounted,
+    enabled: bridge.enabled,
+    dryRun: bridge.dryRun,
+    napcatUrl: bridge.napcatUrl,
+    napcatPort: bridge.napcatPort,
+    tokenKnown: bridge.tokenKnown,
+    bindings: bridge.bindings,
+    configKnown: bridge.configKnown,
+  }
+}
+
+/**
+ * 拿看护的探测结果和桥接配置对一遍：谁的端口指错了、谁的开关没开。
+ *
+ * 顺序按「改起来最省事、后果最严重」排：
+ *   没挂进 profile → 根本没跑，什么都别谈
+ *   指着反向 WS 端口 → HTTP 客户端敲 WebSocket 端口，永远没响应
+ *   端口对不上 → 敲的是空气
+ *   总开关关 / 试运行 → 程序在跑，但一句都不发
+ */
+function bridgeCheck(health, bridge) {
+  if (!bridge || !bridge.found) return { state: 'absent', note: '' }
+  const portUsed = Number((health && health.portUsed) || 0)
+  const bp = Number(bridge.napcatPort || 0)
+  const reverse = String((health && health.mode) || '') === 'reverse'
+
+  let state = 'ok'
+  let note = ''
+  if (!bridge.mounted) {
+    state = 'not-mounted'
+    note = 'dsh-qq-bridge 装了但没挂进 profile（bundles 里没有它、patch 也没 insert），桥接不会跑'
+  } else if (reverse && bp && portUsed && bp === portUsed) {
+    state = 'bridge-hits-reverse'
+    note = `dsh-qq-bridge 连的是 ${bridge.napcatUrl}，而那个端口现在是反向 WebSocket（只收 WebSocket 握手）—— 桥接用 HTTP 敲它就是 426/401。让它改连 NapCat 自己 httpServers 的端口`
+  } else if (!reverse && bp && portUsed && bp !== portUsed) {
+    state = 'port-mismatch'
+    note = `dsh-qq-bridge 连的是 ${bridge.napcatUrl}（端口 ${bp}），NapCat 的 OneBot 接口在 ${portUsed} —— 两边对不上，消息发不出去`
+  } else if (bridge.configKnown && !bridge.enabled) {
+    state = 'disabled'
+    note = 'dsh-qq-bridge 的「总开关」是关的：它在跑，但一句都不会发'
+  } else if (bridge.configKnown && bridge.dryRun) {
+    state = 'dry-run'
+    note = 'dsh-qq-bridge 开着「试运行」：只记账，不真发到 QQ'
+  }
+  return { state, note, bridgePort: bp, portUsed, reverse }
+}
+
+const PROBE_MODES = new Set(['auto', 'http', 'reverse', 'process'])
+
+/** portClients 的缓存：设置页轮询很密，别每 1.5 秒起一个 powershell */
+const linksCache = { port: 0, at: 0, value: null, inflight: null }
+
+/**
+ * 这个端口上现在挂着几个「已经连进来」的客户端？
+ *
+ * 反向 WebSocket 的形态是：端口由 DSH 这边的插件监听（常见是 dsh-onebot-qq），
+ * NapCat 反过来连进去。这种部署下没有任何 HTTP 接口能问「你在线吗」，
+ * 但有件事可以从系统侧看见：这个端口上有没有一条 ESTABLISHED 的回环连接 ——
+ * 有，就说明对面真的连上了。
+ *
+ * 查不出来就返回 count: null。「查不到」和「没连上」是两回事，
+ * 混成一个就会又变成瞎判离线、瞎杀进程。
+ */
+async function portClients(cfg, port = 0, maxAgeMs = 5000) {
+  const p = Number(port) || Number(cfg.onebotPort) || 0
+  if (!p) return { count: null, pids: [], source: 'no-port' }
+  // 设置页 1.5s 轮询 /state，而这个函数要新开一个 powershell：
+  // 缓存 + 同刻只允许一个子进程，否则又是一场 PowerShell 风暴（见 uiCache 那段注释）
+  if (linksCache.port === p && linksCache.value && Date.now() - linksCache.at < maxAgeMs) {
+    return linksCache.value
+  }
+  if (linksCache.port === p && linksCache.inflight) return linksCache.inflight
+  linksCache.port = p
+  linksCache.inflight = (async () => {
+    const self = String(process.pid)
+    // 看的是「谁连进了这个端口」，所以按 RemotePort 找客户端那一侧：
+    // 按 LocalPort 找会命中服务端那条 socket，而它的所有者是跑反向 WS 服务的进程（就是 DSH 自己），
+    // 把它排除掉就一条都数不到了 —— 这个坑第一版就踩了。
+    const script =
+      "$ErrorActionPreference='SilentlyContinue';" +
+      `$c=@(Get-NetTCPConnection -State Established -RemotePort ${p} -ErrorAction SilentlyContinue | ` +
+      `Where-Object { [string]$_.OwningProcess -ne '${self}' });` +
+      `'CLIENTS=' + $c.Count + ' PIDS=' + (($c | Select-Object -ExpandProperty OwningProcess -Unique) -join ',')`
+    const out = await runPs(script, 12000)
+    const m = /CLIENTS=(\d+)\s+PIDS=([0-9,]*)/.exec(String(out || ''))
+    if (!m) return { count: null, pids: [], source: 'ps-fail' }
+    const pids = m[2] ? m[2].split(',').map(Number).filter((n) => Number.isInteger(n) && n > 0) : []
+    return { count: Number(m[1]) || 0, pids, source: 'ps' }
+  })()
+    .then((value) => {
+      linksCache.value = value
+      linksCache.at = Date.now()
+      return value
+    })
+    .finally(() => {
+      linksCache.inflight = null
+    })
+  return linksCache.inflight
+}
+
+/**
+ * 问一句「NapCat 现在怎么样」，顺带分辨端口是被谁占着的。
+ *
+ * 返回的 mode 决定看门狗后面怎么走：
+ *   http     正常 HTTP OneBot 接口，能问到 login_info
+ *   reverse  端口只收 WebSocket（反向 WS 服务在跑，HTTP 换来 426/401）
+ *   auth     端口有响应但拒绝鉴权，多半是 accessToken 对不上
+ *   http     其它 HTTP 响应（不是 OneBot API 该有的样子）
+ *   dead     连不上，端口没开
+ *   process  配置里关了端口探测，只看进程
+ */
+async function probeOnPort(cfg, port, want) {
+  const login = await postOneBot(cfg, 'get_login_info', {}, 4000, port)
   const data = login && login.data
+  const status = Number(login && login.status) || 0
   const online = Boolean(login && login.retcode === 0 && data && (data.user_id || data.uin))
-  return {
+  const portAlive = status > 0
+  const result = {
     online,
     retcode: login && login.retcode,
+    status,
+    portAlive,
+    mode: 'dead',
+    clients: null,
     nickname: online ? data.nickname : '',
     userId: online ? data.user_id || data.uin : '',
-    error: online ? '' : String((login && (login.error || login.raw || login.wording)) || 'no response'),
+    error: '',
+    hint: '',
+  }
+  if (online) {
+    result.mode = 'http'
+    return result
+  }
+  if (want === 'process') {
+    result.mode = 'process'
+    result.error = '按配置只看进程（probeMode=process）'
+    return result
+  }
+  if (!portAlive) {
+    result.error = String((login && (login.error || login.raw || login.wording)) || 'no response')
+    result.hint = '端口连不上'
+    return result
+  }
+  // 端口肯回 HTTP，说明有个服务在听 —— 这本身就意味着「进程是活的」，不该被杀
+  const links = await portClients(cfg, port)
+  result.clients = links.count
+  if (want === 'reverse') {
+    result.mode = 'reverse'
+  } else if (status === 426) {
+    // 426 = 服务端只收 WebSocket 升级。auto 直接判反向；设了「只认 HTTP」就老实说端口回的是 426
+    result.mode = want === 'http' ? 'http' : 'reverse'
+  } else if (status === 401) {
+    // 反向 WS 服务对任何 HTTP 请求都回 401，NapCat 的 HTTP API 令牌不对也回 401，
+    // 靠「有没有客户端连进来」区分这两件事
+    result.mode = links.count !== null && links.count > 0 ? 'reverse' : 'auth'
+  } else {
+    result.mode = 'http'
   }
+  if (result.mode === 'reverse') {
+    if (links.count === null) {
+      result.hint = '反向 WebSocket 服务在跑（这个端口不收 HTTP），客户端数暂时查不到'
+    } else if (links.count > 0) {
+      result.online = true
+      result.hint = `反向 WebSocket 已连上 ${links.count} 个客户端`
+    } else {
+      result.hint = '反向 WebSocket 服务在跑，但还没有客户端连进来'
+    }
+    result.error = result.online ? '' : result.hint
+    return result
+  }
+  result.error = `端口有响应但 ${status === 401 ? '要求鉴权' : `回的是 HTTP ${status}`}`
+  result.hint =
+    status === 401
+      ? 'HTTP 401：多半是 accessToken 和对面配的不一致；如果对面只开反向 WebSocket，把探测方式改成「反向 WebSocket」'
+      : `HTTP ${status}：这个端口上跑的可能不是 OneBot 接口`
+  return result
+}
+
+/**
+ * 探测「NapCat 现在在线吗」，并顺手处理「端口是别人在听」这件事。
+ *
+ * 顺序：
+ *   1. 先探用户自己填的端口（onebotPort）—— 用户显式配置永远优先；
+ *   2. 那个端口不通/不像 OneBot，而机器上挂着 dsh-onebot-qq（反向 WS），
+ *      就去它的端口再问一次：那边只收 WebSocket，会回 426/401，但那已经能说明
+ *      「服务在听、NapCat 有地方连」，这时把 portUsed 指过去（followed=true）；
+ *   3. 提示里带上令牌一致性 / 有没有真的挂载 —— 这两条是最常见的人为卡点。
+ *
+ * 所有分支都返回 portUsed（真正在看的端口）和 followed（是不是跟随了对面），
+ * 看门狗和界面都拿这两个值说话，别再各自猜 cfg.onebotPort。
+ */
+async function probe(cfg, options = {}) {
+  const want = PROBE_MODES.has(cfg.probeMode) ? cfg.probeMode : 'auto'
+  const ownPort = Number(cfg.onebotPort) || 0
+  const comp =
+    options && Object.prototype.hasOwnProperty.call(options, 'companion')
+      ? options.companion
+      : detectCompanion()
+  const tokenMatch = companionTokenMatch(cfg, comp)
+  // 桥接（dsh-qq-bridge）只是「顺便看一眼」，不参与「探哪个端口」的决策，所以可以注入桩
+  const bridge =
+    options && Object.prototype.hasOwnProperty.call(options, 'bridge') ? options.bridge : detectBridge()
+  const wrap = (health, extra = {}) => {
+    const out = {
+      ...health,
+      portUsed: health.portUsed || ownPort,
+      followed: Boolean(extra.followed),
+      primaryPort: ownPort,
+      primaryMode: extra.primaryMode || health.mode,
+      companion: companionPublic(comp),
+      companionTokenMatch: tokenMatch,
+    }
+    const check = bridgeCheck(out, bridge)
+    const pub = bridgePublic(bridge)
+    // 提示文案统一挂在 bridge.note 上，不塞进 hint：现有自检对 hint 有精确断言，
+    // 而且「桥接指错端口」和「NapCat 自己正不正常」是两件事，混在一句话里反而看不清。
+    out.bridge = pub ? { ...pub, check: check.state, note: check.note } : null
+    return out
+  }
+
+  const first = await probeOnPort(cfg, ownPort, want)
+  first.portUsed = ownPort
+  if (first.online || want === 'process') return wrap(first)
+
+  const follow =
+    cfg.companionFollow !== false &&
+    comp &&
+    comp.found &&
+    comp.mounted &&
+    comp.mode === 'reverse' &&
+    Number(comp.port) > 0 &&
+    Number(comp.port) !== ownPort
+
+  if (follow) {
+    const alt = await probeOnPort(cfg, Number(comp.port), 'auto')
+    alt.portUsed = Number(comp.port)
+    if (alt.mode === 'reverse' || alt.online) {
+      const hintBits = []
+      if (alt.hint) hintBits.push(alt.hint)
+      hintBits.push(
+        `你填的 ${ownPort} 上没有 OneBot 服务，已跟随 dsh-onebot-qq 的反向 WS 端口 ${comp.port}`,
+      )
+      if (tokenMatch === false) {
+        hintBits.push('⚠ 两边的 accessToken 不一致：NapCat 连上去会被 4401 拒绝，改成一样再试')
+      } else if (comp.tokenKnown && tokenMatch === true && comp.token) {
+        hintBits.push('accessToken 两边一致')
+      }
+      alt.hint = hintBits.join('；')
+      if (alt.error) alt.error = alt.hint
+      return wrap(alt, { followed: true, primaryMode: first.mode })
+    }
+  }
+
+  // 没跟上：把「为什么没跟上」讲清楚，别让人自己去猜
+  const bits = []
+  if (first.hint) bits.push(first.hint)
+  if (comp && comp.found) {
+    if (!comp.mounted) {
+      bits.push(
+        `检测到 ${COMPANION_PACKAGE} 已安装（${comp.packageVersion || '版本未知'}）但没挂进 profile：` +
+          'bundles 里没有它、patch 里也没有 insert，所以它的反向 WS 端口根本不会开',
+      )
+    } else if (comp.mode === 'forward') {
+      bits.push(
+        `${COMPANION_PACKAGE} 现在是 forward 模式（主动连 ${comp.url}）：此时端口该由 NapCat 自己开，` +
+          '反向 WS 那条路用不上',
+      )
+    } else if (comp.port && comp.port !== ownPort && cfg.companionFollow === false) {
+      bits.push(`${COMPANION_PACKAGE} 的反向 WS 在 ${comp.port}，但「跟随 dsh-onebot-qq」关了`)
+    }
+  }
+
+  // 端口回 401 且我们有令牌：多半就是两边令牌不一致，这里直接点破
+  if (first.mode === 'auth' && comp && comp.found && tokenMatch === false) {
+    bits.push(`⚠ ${COMPANION_PACKAGE} 配的 accessToken 和本插件不一致（它的是 ${comp.token ? '另一串' : '空'}），这件事光重启 NapCat 解决不了`)
+  }
+  const merged = bits.filter(Boolean).join('；')
+  if (merged) first.hint = merged
+  return wrap(first, { primaryMode: first.mode })
 }
 
 /* ------------------------------------------------------------------ */
@@ -2279,6 +2967,7 @@ function launchNapcat(cfg, reason = '') {
       writeLock(cfg)
       state.lastLaunchAt = Date.now()
       state.launchCount += 1
+      state.launchFails += 1
       state.phase = 'launching'
       state.scanSince = 0
       state.lastError = ''
@@ -2336,6 +3025,7 @@ function launchNapcat(cfg, reason = '') {
   writeLock(cfg)
   state.lastLaunchAt = Date.now()
   state.launchCount += 1
+  state.launchFails += 1
   state.phase = 'launching'
   state.scanSince = 0
   state.lastError = ''
@@ -2420,14 +3110,27 @@ async function tick(cfg) {
   state.cfg = cfg
   state.lastProbeAt = new Date().toISOString()
   const health = await probe(cfg)
+  /** 真正在看的端口：可能跟随了 dsh-onebot-qq 的反向 WS 端口 */
+  const portShown = health.portUsed || cfg.onebotPort
 
   if (health.online) {
-    if (state.phase !== 'online') log(cfg, `ONLINE: ${health.nickname} (${health.userId})`)
+    if (state.phase !== 'online') {
+      const who =
+        health.nickname || health.userId
+          ? `${health.nickname} (${health.userId})`
+          : health.mode === 'reverse'
+            ? '反向 WebSocket 已连接'
+            : '已连接'
+      log(cfg, `ONLINE${health.mode === 'reverse' ? '[reverse]' : ''}: ${who}`)
+    }
     state.phase = 'online'
     state.lastOnlineAt = Date.now()
     state.lastError = ''
     state.scanSince = 0
     state.scanRetries = 0
+    // 真连上了就把失败计数清掉，下次出事重新给足宽限
+    state.launchFails = 0
+    state.reverseRetries = 0
     const bridge = bridgeAge(cfg)
     if (bridge.ageSec !== null && bridge.ageSec > cfg.bridgeStaleSec) {
       log(cfg, `WARN bridge state stale ${bridge.ageSec}s (${bridge.path}) —— 桥接可能卡住`)
@@ -2450,7 +3153,9 @@ async function tick(cfg) {
       online: true,
       nickname: health.nickname,
       userId: health.userId,
-      port: cfg.onebotPort,
+      port: portShown,
+      mode: health.mode,
+      clients: health.clients,
       bridge,
       launches: state.launchCount,
       dedupes: state.dedupeCount,
@@ -2503,10 +3208,116 @@ async function tick(cfg) {
     return { phase: state.phase, health, procs, deduped: true, launched }
   }
 
+  const hasProcess = procs.boot > 0 || procs.qq > 0
+
+  /*
+   * 反向 WebSocket（dsh-onebot-qq 这类插件占着端口，NapCat 反过来连进去）：
+   * 这种部署下 HTTP 永远问不出「在线」，只能看端口上有没有客户端连进来。
+   * 关键的一条：进程在 + 端口有服务，就别杀 —— 老版本在这儿一路判离线，无限重拉。
+   */
+  if (health.mode === 'reverse' && hasProcess) {
+    if (health.clients === null) {
+      // 客户端数查不到：模糊信息不杀人，先按在线处理，日志里留一句
+      if (state.phase !== 'online') log(cfg, 'REVERSE: 查不到反向 WS 客户端数，按「在线」处理（不重启）')
+      state.phase = 'online'
+      state.lastOnlineAt = Date.now()
+      state.lastError = ''
+      state.launchFails = 0
+      writeSnapshot(cfg, {
+        phase: state.phase,
+        online: true,
+        mode: health.mode,
+        clients: null,
+        procs,
+        port: portShown,
+        updatedAt: new Date().toISOString(),
+      })
+      return { phase: state.phase, health, procs }
+    }
+    const waitedSec = state.lastLaunchAt ? Math.round((Date.now() - state.lastLaunchAt) / 1000) : 0
+    const overStuck = state.lastLaunchAt ? Date.now() - state.lastLaunchAt > cfg.stuckSec * 1000 : true
+    if (overStuck && state.reverseRetries < 2) {
+      state.reverseRetries += 1
+      log(
+        cfg,
+        `REVERSE-WAIT ${waitedSec}s 端口上还没有客户端连进来 → 温和重拉一次 ` +
+          `(${state.reverseRetries}/2)。若反复这样，检查 NapCat 里的反向 WS 地址是不是 ` +
+          `ws://127.0.0.1:${portShown}（令牌要对上 accessToken）`,
+      )
+      const cleaned = await killNapcat(cfg)
+      if (cleaned) {
+        await sleep(1200)
+        launchNapcat(cfg, 'reverse-wait')
+      } else {
+        log(cfg, 'REVERSE-WAIT: 旧链没清干净，先不拉新链')
+      }
+      writeSnapshot(cfg, {
+        phase: 'launching',
+        online: false,
+        mode: health.mode,
+        procs,
+        relaunched: cleaned,
+        updatedAt: new Date().toISOString(),
+      })
+      return { phase: 'launching', health, procs, relaunched: cleaned }
+    }
+    const before = state.phase
+    state.phase = overStuck ? 'reverse-giveup' : 'reverse-wait'
+    state.lastError = health.hint || health.error
+    if (before !== state.phase) {
+      if (state.phase === 'reverse-giveup') {
+        log(
+          cfg,
+          `REVERSE-GIVEUP: ${waitedSec}s 里 NapCat 一直没连上反向 WS，重拉 ${state.reverseRetries} 次也没用。` +
+            `去 NapCat 配置里把「反向 WebSocket」地址填成 ws://127.0.0.1:${portShown}` +
+            '（令牌对上 accessToken），改完把设置里的「在线探测方式」留 auto 就行。',
+        )
+      } else {
+        log(cfg, `REVERSE-WAIT: ${health.hint || '等 NapCat 连反向 WS'}（不重启，等它自己连）`)
+      }
+    }
+    writeSnapshot(cfg, {
+      phase: state.phase,
+      online: false,
+      mode: health.mode,
+      clients: health.clients,
+      procs,
+      port: portShown,
+      updatedAt: new Date().toISOString(),
+    })
+    return { phase: state.phase, health, procs }
+  }
+
+  /*
+   * 端口肯回 HTTP，但回的是 401 或别的状态：说明有服务在听、NapCat 进程也在。
+   * 这时候「杀掉重拉」什么也解决不了（令牌不对、或者端口被别的程序占着），
+   * 单独报出来，别再掉进 STUCK 那条死循环。
+   */
+  if (health.portAlive && health.mode !== 'reverse' && hasProcess) {
+    const before = state.phase
+    state.phase = health.mode === 'auth' ? 'need-token' : 'port-busy'
+    state.lastError = health.error || health.hint
+    if (before !== state.phase) {
+      log(cfg, `${state.phase.toUpperCase()}: ${health.error} —— ${health.hint}（不重启）`)
+    }
+    writeSnapshot(cfg, {
+      phase: state.phase,
+      online: false,
+      mode: health.mode,
+      status: health.status,
+      procs,
+      port: portShown,
+      updatedAt: new Date().toISOString(),
+    })
+    return { phase: state.phase, health, procs }
+  }
+
   // ② 完全没有进程：拉起（带宽限期 + 跨进程锁）
   if (procs.boot === 0 && procs.qq === 0) {
     const since = Date.now() - state.lastLaunchAt
-    if (since < cfg.launchGraceSec * 1000) {
+    // 连续拉不起来就别每轮的宽限期都硬等一遍：2 的幂放大，最多 8 倍
+    const backoff = Math.min(2 ** Math.min(state.launchFails, 3), 8)
+    if (since < cfg.launchGraceSec * backoff * 1000) {
       state.phase = 'launching'
       writeSnapshot(cfg, { phase: state.phase, online: false, procs, launches: state.launchCount })
       return { phase: state.phase, health, procs }
@@ -2703,11 +3514,31 @@ function registerTools(ctx, cfg) {
                 phase: state.phase,
                 onebot: {
                   port: cfg.onebotPort,
+                  /** 真正在看的端口：跟随了 dsh-onebot-qq 时和上面那个不一样 */
+                  portUsed: health.portUsed || cfg.onebotPort,
+                  followedCompanion: Boolean(health.followed),
                   online: health.online,
+                  /** http / reverse / auth / http / process / dead —— 反向 WS 时看这个 */
+                  mode: health.mode,
+                  portAlive: health.portAlive,
+                  httpStatus: health.status,
+                  /** 反向 WS 模式下端口上连进来的客户端数（null = 查不到） */
+                  clients: health.clients,
+                  hint: health.hint,
                   nickname: health.nickname,
                   user_id: health.userId,
                   error: health.error,
                 },
+                companion: {
+                  /** 本机装没装 dsh-onebot-qq、挂没挂、它自己配成什么样（不含令牌明文） */
+                  onebot: {
+                    ...(health.companion || companionPublic(detectCompanion()) || { found: false }),
+                    tokenMatches:
+                      health.companionTokenMatch === undefined ? null : health.companionTokenMatch,
+                  },
+                  /** dsh-qq-bridge：装没装、挂没挂、桥接指向的端口和 NapCat 对不上没有 */
+                  bridge: health.bridge || bridgePublic(detectBridge()) || { found: false },
+                },
                 procs,
                 node: nodePublic(cfg),
                 qr,
@@ -2734,7 +3565,21 @@ function registerTools(ctx, cfg) {
                 logTail: tail,
                 note: health.online
                   ? '在线。若 QQ 里还是没回音，问题在 dsh-qq-bridge 那一侧（绑定/试运行开关）。'
-                  : qr && qr.ageSec <= cfg.qrFreshSec
+                  : health.mode === 'reverse'
+                    ? health.clients === null
+                      ? '反向 WebSocket 模式：端口是反向 WS 服务在听（HTTP 问不出在线），客户端数还查不到——按在线处理，不会重启。'
+                      : '反向 WebSocket 模式：端口活着，但还没有客户端连进来。让 NapCat 把反向 WS 地址填成 ws://127.0.0.1:' +
+                        String(health.portUsed || cfg.onebotPort) +
+                        '（令牌对上 accessToken）；超过 stuckSec 才会温和重拉，最多两次。'
+                    : health.mode === 'auth'
+                      ? '端口有响应但要求鉴权（HTTP ' +
+                        String(health.status) +
+                        '）：多半是 accessToken 跟 NapCat（或反向 WS 服务）里填的不一致。不会重启，先把令牌对一下。'
+                      : health.portAlive
+                        ? '端口活着但回的不是 OneBot 接口（HTTP ' +
+                          String(health.status) +
+                          '）：看看是不是别的程序占着这个端口。不会重启。'
+                        : qr && qr.ageSec <= cfg.qrFreshSec
                     ? passwordActive(cfg)
                       ? '离线，且在等扫码——但「记住密码」是开着的：看一眼日志里“快速登录错误”后面是不是仍回退到二维码（密码登录可能被腾讯要求验证）。'
                       : '离线，且二维码是新的：需要手机扫码（或在设置里打开「记住密码」让 NapCat 自己用密码登录）。文件在 qrCopyPath。'
@@ -2917,6 +3762,10 @@ function publicConfig(cfg) {
     passwordActive: passwordActive(cfg),
     onebotPort: cfg.onebotPort,
     accessToken: cfg.accessToken,
+    probeMode: cfg.probeMode,
+    companionFollow: cfg.companionFollow,
+    /** 这一行该不该出现在设置页：装了且挂进 profile 才给界面渲染 */
+    companionReady: Boolean(cfg.companionReady),
     procPathMatch: cfg.procPathMatch,
     probeIntervalSec: cfg.probeIntervalSec,
     launchGraceSec: cfg.launchGraceSec,
@@ -3072,6 +3921,14 @@ async function uiState(cfg, options = {}) {
   const p = procs || { boot: 0, qq: 0, chains: 0, dup: false }
   const qr = cachedQr(cfg)
   const bridge = bridgeAge(cfg)
+  // 面板每轮都来问一次（轻量档 1.5s 一轮），顺手按最新探测结果校准「跟随」那一项：
+  // 用户中途把 dsh-onebot-qq 挂进 profile（或者摘掉），不用重启 DSH —— 界面上那一行立刻跟着出现/消失，
+  // 值仍然是「他自己想要的那个」被闸门压过之后的结果（显式关过就一直关）。
+  const liveReady = companionReady(health.companion || detectCompanion())
+  if (liveReady !== cfg.companionReady) {
+    cfg.companionReady = liveReady
+    cfg.companionFollow = liveReady ? cfg.companionFollowWant !== false : false
+  }
   return {
     ok: true,
     version,
@@ -3081,6 +3938,21 @@ async function uiState(cfg, options = {}) {
       enabled: cfg.enabled,
       phase: state.phase,
       online: !!health.online,
+      /** http / reverse / auth / http-odd / process / dead —— 设置页据此显示「反向 WS」那套词 */
+      mode: health.mode || '',
+      portAlive: !!health.portAlive,
+      portStatus: health.status || 0,
+      /** 真正在看的端口（可能跟随了 dsh-onebot-qq） */
+      portUsed: health.portUsed || cfg.onebotPort,
+      followed: Boolean(health.followed),
+      companion: health.companion || companionPublic(detectCompanion()),
+      /** 设置页「跟随 dsh-onebot-qq」那一行显不显示，就看它（装了且挂进 profile） */
+      companionReady: Boolean(cfg.companionReady),
+      companionTokenMatch: health.companionTokenMatch === undefined ? null : health.companionTokenMatch,
+      /** dsh-qq-bridge 的共存情况（键名避开下面表示心跳新鲜度的 bridge） */
+      bridgePlugin: health.bridge || bridgePublic(detectBridge()),
+      clients: health.clients,
+      hint: health.hint || '',
       nickname: health.nickname || '',
       userId: health.userId || 0,
       error: health.error || '',
@@ -3138,6 +4010,9 @@ function saveAndApply(ctx, patch) {
   const fileCfg = { ...readConfigFile(dir) }
   for (const [key, value] of Object.entries(patch || {})) {
     if (!Object.prototype.hasOwnProperty.call(DEFAULTS, key)) continue
+    // 界面上没有这一行时（dsh-onebot-qq 没装/没启用），前端发的全量 patch 里可能带着假值，
+    // 别让它把用户以前存的选择覆盖掉 —— 等它真的启用了再说。
+    if (key === 'companionFollow' && !companionReady(detectCompanion())) continue
     if (key === 'quickPassword') {
       // 设置页不回显密码：空字符串 = 别动它（要清空走 clearPassword 动作）
       const text = String(value == null ? '' : value).replace(/[\r\n]/g, '')
@@ -3488,6 +4363,27 @@ export const __internals = {
   procRoot,
   probe,
   probeProcs,
+  portClients,
+  PROBE_MODES,
+  // 与 dsh-onebot-qq 共存：识别它的安装/挂载/配置（自检脚本直接调这几个）
+  detectCompanion,
+  parseCompanionConfig,
+  companionPublic,
+  companionReady,
+  companionTokenMatch,
+  probeOnPort,
+  COMPANION_DEFAULTS,
+  COMPANION_PACKAGE,
+  // 与 dsh-qq-bridge 共存：它是「客户端」，配置摊在 ~/.dsh/qq-bridge-config.json
+  profileHits,
+  detectBridge,
+  bridgePublic,
+  bridgeCheck,
+  readBridgeConfig,
+  urlPort,
+  BRIDGE_DEFAULTS,
+  BRIDGE_PACKAGE,
+  BRIDGE_ID,
   qrInfo,
   bridgeAge,
   launchNapcat,