dsh-napcat-keeper 2.8.0 → 2.8.1

package/lib/index.js

@@ -1,9 +1,24 @@
 /**
- * dsh-napcat-keeper —— NapCat 看门狗 v2.8.0（可发布通用版）
+ * 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 不看状态码，于是把「端口在回话」当成「端口不通」
@@ -147,7 +162,7 @@ import { homedir, tmpdir } from 'node:os'
 import path from 'node:path'
 
 export const name = 'napcat-keeper'
-export const version = '2.8.0'
+export const version = '2.8.1'
 
 /** tools 用来注册 napcat_* 工具；webServer 用来挂设置界面接口。拿不到也不至于把 DSH 拖崩。 */
 export const inject = ['tools', 'webServer']
@@ -188,6 +203,12 @@ const DEFAULTS = {
    *   process  只看进程在不在，不碰端口
    */
   probeMode: 'auto',
+  /**
+   * 跟随 dsh-onebot-qq：自己填的端口连不上、而机器上挂着的 dsh-onebot-qq 是反向 WS 模式时，
+   * 自动把探测指向它监听的那个端口（用户显式填的端口一旦通了就还是用用户的）。
+   * 默认开 —— 这正是「装了反向 WS 插件却一直判离线」那个坑的解药。
+   */
+  companionFollow: true,
   /** 只在这些路径下找 QQ/NapCat 进程；留空 = 由 shellDir 推导（上层目录） */
   procPathMatch: '',
   /** 复查间隔（秒） */
@@ -788,6 +809,7 @@ function normalizeConfig(cfg) {
   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)
@@ -816,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')
@@ -896,7 +933,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
  * 对方根本不会回 OneBot 的 JSON，能拿到的唯一线索就是 401 / 426 这类状态码 ——
  * 老版本把状态码丢了，于是一律当成「端口不通」，接着就是杀掉重拉，无限循环。
  */
-function postOneBot(cfg, action, payload, timeoutMs = 4000) {
+function postOneBot(cfg, action, payload, timeoutMs = 4000, port = 0) {
   return new Promise((resolve) => {
     const body = JSON.stringify(payload || {})
     const headers = {
@@ -909,7 +946,7 @@ 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,
@@ -957,6 +994,397 @@ function postOneBot(cfg, action, payload, timeoutMs = 4000) {
   })
 }
 
+/* ------------------------------------------------------------------ */
+/* 和 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 */
@@ -973,16 +1401,16 @@ const linksCache = { port: 0, at: 0, value: null, inflight: null }
  * 查不出来就返回 count: null。「查不到」和「没连上」是两回事，
  * 混成一个就会又变成瞎判离线、瞎杀进程。
  */
-async function portClients(cfg, maxAgeMs = 5000) {
-  const port = Number(cfg.onebotPort) || 0
-  if (!port) return { count: null, pids: [], source: 'no-port' }
+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 === port && linksCache.value && Date.now() - linksCache.at < maxAgeMs) {
+  if (linksCache.port === p && linksCache.value && Date.now() - linksCache.at < maxAgeMs) {
     return linksCache.value
   }
-  if (linksCache.port === port && linksCache.inflight) return linksCache.inflight
-  linksCache.port = port
+  if (linksCache.port === p && linksCache.inflight) return linksCache.inflight
+  linksCache.port = p
   linksCache.inflight = (async () => {
     const self = String(process.pid)
     // 看的是「谁连进了这个端口」，所以按 RemotePort 找客户端那一侧：
@@ -990,7 +1418,7 @@ async function portClients(cfg, maxAgeMs = 5000) {
     // 把它排除掉就一条都数不到了 —— 这个坑第一版就踩了。
     const script =
       "$ErrorActionPreference='SilentlyContinue';" +
-      `$c=@(Get-NetTCPConnection -State Established -RemotePort ${port} -ErrorAction 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)
@@ -1021,9 +1449,8 @@ async function portClients(cfg, maxAgeMs = 5000) {
  *   dead     连不上，端口没开
  *   process  配置里关了端口探测，只看进程
  */
-async function probe(cfg) {
-  const want = PROBE_MODES.has(cfg.probeMode) ? cfg.probeMode : 'auto'
-  const login = await postOneBot(cfg, 'get_login_info')
+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))
@@ -1055,7 +1482,7 @@ async function probe(cfg) {
     return result
   }
   // 端口肯回 HTTP，说明有个服务在听 —— 这本身就意味着「进程是活的」，不该被杀
-  const links = await portClients(cfg)
+  const links = await portClients(cfg, port)
   result.clients = links.count
   if (want === 'reverse') {
     result.mode = 'reverse'
@@ -1089,6 +1516,109 @@ async function probe(cfg) {
   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 })
+}
+
 /* ------------------------------------------------------------------ */
 /* 进程链 / 二维码 / 桥接新鲜度                                          */
 /* ------------------------------------------------------------------ */
@@ -2580,6 +3110,8 @@ 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') {
@@ -2621,7 +3153,7 @@ async function tick(cfg) {
       online: true,
       nickname: health.nickname,
       userId: health.userId,
-      port: cfg.onebotPort,
+      port: portShown,
       mode: health.mode,
       clients: health.clients,
       bridge,
@@ -2697,7 +3229,7 @@ async function tick(cfg) {
         mode: health.mode,
         clients: null,
         procs,
-        port: cfg.onebotPort,
+        port: portShown,
         updatedAt: new Date().toISOString(),
       })
       return { phase: state.phase, health, procs }
@@ -2710,7 +3242,7 @@ async function tick(cfg) {
         cfg,
         `REVERSE-WAIT ${waitedSec}s 端口上还没有客户端连进来 → 温和重拉一次 ` +
           `(${state.reverseRetries}/2)。若反复这样，检查 NapCat 里的反向 WS 地址是不是 ` +
-          `ws://127.0.0.1:${cfg.onebotPort}（令牌要对上 accessToken）`,
+          `ws://127.0.0.1:${portShown}（令牌要对上 accessToken）`,
       )
       const cleaned = await killNapcat(cfg)
       if (cleaned) {
@@ -2737,7 +3269,7 @@ async function tick(cfg) {
         log(
           cfg,
           `REVERSE-GIVEUP: ${waitedSec}s 里 NapCat 一直没连上反向 WS，重拉 ${state.reverseRetries} 次也没用。` +
-            `去 NapCat 配置里把「反向 WebSocket」地址填成 ws://127.0.0.1:${cfg.onebotPort}` +
+            `去 NapCat 配置里把「反向 WebSocket」地址填成 ws://127.0.0.1:${portShown}` +
             '（令牌对上 accessToken），改完把设置里的「在线探测方式」留 auto 就行。',
         )
       } else {
@@ -2750,7 +3282,7 @@ async function tick(cfg) {
       mode: health.mode,
       clients: health.clients,
       procs,
-      port: cfg.onebotPort,
+      port: portShown,
       updatedAt: new Date().toISOString(),
     })
     return { phase: state.phase, health, procs }
@@ -2774,7 +3306,7 @@ async function tick(cfg) {
       mode: health.mode,
       status: health.status,
       procs,
-      port: cfg.onebotPort,
+      port: portShown,
       updatedAt: new Date().toISOString(),
     })
     return { phase: state.phase, health, procs }
@@ -2982,6 +3514,9 @@ 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,
@@ -2994,6 +3529,16 @@ function registerTools(ctx, cfg) {
                   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,
@@ -3024,7 +3569,7 @@ function registerTools(ctx, cfg) {
                     ? health.clients === null
                       ? '反向 WebSocket 模式：端口是反向 WS 服务在听（HTTP 问不出在线），客户端数还查不到——按在线处理，不会重启。'
                       : '反向 WebSocket 模式：端口活着，但还没有客户端连进来。让 NapCat 把反向 WS 地址填成 ws://127.0.0.1:' +
-                        String(cfg.onebotPort) +
+                        String(health.portUsed || cfg.onebotPort) +
                         '（令牌对上 accessToken）；超过 stuckSec 才会温和重拉，最多两次。'
                     : health.mode === 'auth'
                       ? '端口有响应但要求鉴权（HTTP ' +
@@ -3218,6 +3763,9 @@ function publicConfig(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,
@@ -3373,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,
@@ -3386,6 +3942,15 @@ async function uiState(cfg, options = {}) {
       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 || '',
@@ -3445,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, '')
@@ -3797,6 +4365,25 @@ export const __internals = {
   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,