dsh-remote-hub 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,7 @@
 # DSH Remote — Android 远程控制器
 
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/liaoguogang-hub/dsh-remote-public)
+
 手机原生 App，直接控制电脑上的 **DeepSeek Harness (DSH)**。不是 WebView 套壳：
 Kotlin/Compose 直连 DSH 自带的 HTTP API + WebSocket 网关。
 
@@ -15,6 +17,29 @@ Kotlin/Compose 直连 DSH 自带的 HTTP API + WebSocket 网关。
 
 功能与 UI 与自用版 4.12.2 完全一致。
 
+## 下载手机端 App
+
+**DSH Remote v4.19.1** · Android 8.0 (API 26) 及以上 · 2.8 MB
+
+[⬇️ 下载 APK](https://github.com/liaoguogang-hub/dsh-remote-public/releases/download/v4.19.1/DSH-Remote-v4.19.1.apk) ·
+[全部版本](https://github.com/liaoguogang-hub/dsh-remote-public/releases)
+
+安装后应用名「DSH Remote」，包名 `com.dsh.remote.ngrok`（可与作者的 `DSH` 自用版共存）。
+手机端不通过 npm 分发——npm 包 `dsh-remote-hub` 是电脑侧的 DSH 插件，两者配合使用：
+
+```
+电脑：dsh plugin --profile desktop add dsh-remote-hub   → 起桥接 / 开隧道 / 签 Cookie
+手机：装上面这个 APK → 填电脑给出的地址与 Cookie → 连接
+```
+
+## 扫码配对（手机端）
+
+电脑上 `dsh-remote qr` 打开配对页 → 手机 App「设置 → 扫码配对」扫一下就自动填好地址与凭据，
+不用手抄 Cookie。
+
+二维码里**不含 Cookie**：只含一个 **10 分钟有效、用一次就作废**的配对码。
+相机不可用时可以点「手动输入」，填地址 + 配对码同样能连上。
+
 ## 功能
 
 | 能力 | 状态 |
@@ -157,10 +182,12 @@ node mint.mjs "127.0.0.1:1815" 30              # 签发 30 天 Cookie
 并把地址与 Cookie 写进 `~/.dsh/dsh-remote/`，手机 App 直接抄。
 
 ```bash
-# 从 NPM 安装（发布后可用，会出现在 DSH 内的「插件中心」）
-dsh plugin --profile web add dsh-remote-hub
+# 从 NPM 安装（推荐，会出现在 DSH 内的「插件中心」）
+# https://www.npmjs.com/package/dsh-remote-hub
+dsh plugin --profile desktop add dsh-remote-hub
+dsh plugin --profile web add dsh-remote-hub      # web profile 同样可用
 
-# 或直接从本仓库源码安装（不需要 NPM 发布）
+# 或直接从本仓库源码安装（不经过 NPM）
 dsh plugin --profile web add github:liaoguogang-hub/dsh-remote-public
 ```
 
@@ -174,6 +201,8 @@ dsh plugin --profile web add github:liaoguogang-hub/dsh-remote-public
 查看结果：
 
 ```bash
+dsh-remote qr         # 打开配对页（二维码），手机扫一下就自动填好
+dsh-remote start --open   # 起桥接并打印地址/Cookie，同时打开二维码页（connect.cmd 用的就是它）
 dsh-remote status     # 局域网地址、公网地址、Cookie、上游端口
 dsh-remote connect    # 直接打印要抄进手机的两行
 dsh-remote doctor     # 逐项自检：凭据、ngrok、cloudflared、宿主端口
@@ -192,3 +221,29 @@ dsh-remote start      # 不开 DSH 也能单独前台跑（Ctrl+C 退出）
 
 > 公网隧道受网络影响：`api.trycloudflare.com` 不可达时插件会跳过公网、只给局域网地址，
 > 并在 `status.json` 里写明原因，不会假装成功。
+
+### 扫码配对（一次性配对码）
+
+不想手抄 Cookie 就用二维码：
+
+```bash
+dsh-remote qr
+```
+
+浏览器会打开 `http://127.0.0.1:6300/_dsh-remote/pair`，显示一个二维码。手机 DSH Remote 里点
+「扫码配对」，扫完自动填入地址并换取登录凭据，直接连上。
+
+扫码后会自动判断：返回的是私有地址就填进「局域网」，公网地址填进「自定义」。
+
+安全设计：
+- 二维码里**不含 Cookie**，只含一个 **10 分钟有效的一次性配对码**（`{"v":1,"u":"<地址>","c":"<配对码>","e":<过期时间>}`）；
+- 兑换成功即作废，截图/偷拍泄漏的是一个立刻失效的码，而不是 30 天访问权；
+- 配对码只存在内存里，插件重启即全部失效（失效安全）。
+
+端点（都在桥接上，不经 DSH）：
+
+| 方法 | 路径 | 作用 |
+|---|---|---|
+| GET | `/_dsh-remote/pair` | 配对页（二维码 HTML） |
+| GET | `/_dsh-remote/pair.svg` | 只要二维码 SVG |
+| POST | `/_dsh-remote/pair/redeem` | `{code}` → `{url, cookie}`；用过即失效 |

package/bin/dsh-remote.mjs

@@ -5,14 +5,16 @@
  *   dsh-remote status      show LAN URL, public URL, cookie and upstream port
  *   dsh-remote connect     print the two lines to paste into the phone
  *   dsh-remote cookie      print only the cookie
- *   dsh-remote start       run the supervisor in the foreground (Ctrl+C stops it)
+ *   dsh-remote start [--open]  run the supervisor in the foreground; --open 打印地址并打开配对页
  *   dsh-remote stop        ask a foreground `start` to stop (best effort, via status file)
  *   dsh-remote doctor      check every prerequisite in one pass
+ *   dsh-remote qr          open the pairing page (QR) in the default browser
  *
  * @module bin/dsh-remote
  */
 
 import fs from 'node:fs'
+import { execFile } from 'node:child_process'
 import os from 'node:os'
 import path from 'node:path'
 
@@ -45,6 +47,7 @@ function printStatus() {
   console.log(`  桥接端口     ${status.bridgePort}`)
   console.log(`  DSH 上游     ${status.upstreamPort ? '127.0.0.1:' + status.upstreamPort : '未找到'}`)
   console.log(`  更新时间     ${new Date(status.updatedAt).toLocaleString()}`)
+  if (status.bridgePort) console.log(`  扫码配对     dsh-remote qr   （或 http://127.0.0.1:${status.bridgePort}/_dsh-remote/pair）`)
   if (status.cookie) {
     console.log(`  Cookie 到期  ${fmtTime(status.cookieExpiresAt)}${remaining !== null ? `（还剩 ${remaining} 天）` : ''}`)
     console.log('')
@@ -58,6 +61,39 @@ function printStatus() {
   console.log('')
 }
 
+function openBrowser(url) {
+  const cmd = process.platform === 'win32' ? 'cmd' : process.platform === 'darwin' ? 'open' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  return new Promise((resolve) => {
+    execFile(cmd, args, { windowsHide: true }, () => resolve())
+  })
+}
+
+/** Point the browser at the running bridge's pairing page (port comes from status, not a constant). */
+async function openPairPage(bridgePort) {
+  const page = `http://127.0.0.1:${bridgePort}/_dsh-remote/pair`
+  console.log('')
+  console.log('  配对页：', page)
+  console.log('  手机点右上角扫码按钮，扫这个二维码即可（10 分钟内有效，用一次作废）')
+  console.log('')
+  await openBrowser(page)
+}
+
+async function qrCommand() {
+  const status = readStatus()
+  const port = status?.bridgePort ?? Number(process.env.DSH_REMOTE_PORT || 6300)
+  const page = `http://127.0.0.1:${port}/_dsh-remote/pair`
+  console.log('')
+  console.log('  配对页：', page)
+  console.log('  用手机 DSH Remote 的「扫码配对」扫屏幕上的二维码（10 分钟内有效，只能用一次）')
+  console.log('')
+  if (process.argv.includes('--no-open')) {
+    console.log('  （--no-open：未自动打开浏览器）')
+    return
+  }
+  await openBrowser(page)
+}
+
 async function doctor() {
   console.log('')
   console.log('  dsh-remote 自检')
@@ -117,8 +153,36 @@ async function main() {
     case 'doctor':
       await doctor()
       break
+    case 'qr':
+    case 'pair':
+      await qrCommand()
+      break
     case 'start': {
-      const handle = await start({ log: (m) => console.log(m) })
+      const wantOpen = process.argv.includes('--open')
+      let handle
+      try {
+        handle = await start({ log: (m) => console.log(m) })
+      } catch (err) {
+        // Port already taken: another bridge is serving; just show its pairing page.
+        if (/EADDRINUSE/.test(String(err?.message ?? err))) {
+          const running = readStatus()
+          const port = running?.bridgePort
+          if (port) {
+            console.log(`已有桥接在 127.0.0.1:${port} 运行，直接复用它`)
+            if (wantOpen) await openPairPage(port)
+            return
+          }
+        }
+        throw err
+      }
+      const status = handle.status
+      if (status?.cookie) {
+        console.log('')
+        console.log('  DSH 地址（局域网）：', status.lan?.url ?? '(未检测到局域网 IP)')
+        console.log('  DSH 地址（公网）  ：', status.public?.url ?? `无（${status.public?.note ?? '未开启'}）`)
+        console.log('  Cookie            ：', status.cookie)
+      }
+      if (wantOpen) await openPairPage(status?.bridgePort ?? Number(process.env.DSH_REMOTE_PORT || 6300))
       process.on('SIGINT', async () => {
         await handle.close()
         process.exit(0)
@@ -130,7 +194,7 @@ async function main() {
       break
     default:
       console.log(`未知命令：${command}`)
-      console.log('可用：status | connect | cookie | doctor | start | stop')
+      console.log('可用：status | connect | cookie | qr | doctor | start | stop')
       process.exitCode = 1
   }
 }

package/lib/bridge.js

@@ -20,6 +20,8 @@ import http from 'node:http'
 import net from 'node:net'
 import zlib from 'node:zlib'
 
+import { handlePairing } from './pairing-routes.js'
+
 const LIST_PATH = '/api/session/list'
 
 function rewriteHeaders(headers, authority) {
@@ -66,7 +68,7 @@ function trimSessionList(body) {
  * @param {(msg: string) => void} [options.log]
  * @returns {Promise<{close: () => Promise<void>, port: number}>}
  */
-export function startBridge({ listenPort, authority, upstream, log = () => {} }) {
+export function startBridge({ listenPort, authority, upstream, pairing = null, log = () => {} }) {
   const forward = (req, res, attempt = 0) =>
     new Promise((resolve) => {
       upstream.resolve(attempt > 0).then((port) => {
@@ -147,6 +149,17 @@ export function startBridge({ listenPort, authority, upstream, log = () => {} })
     })
 
   const server = http.createServer((req, res) => {
+    // Pairing is served by the bridge itself: it must work before the phone has any credential,
+    // and it must NOT be proxied to DSH.
+    if (pairing && String(req.url || '').startsWith('/_dsh-remote/pair')) {
+      handlePairing({ req, res, current: pairing.current, store: pairing.store }).catch(() => {
+        try {
+          res.writeHead(500)
+          res.end('dsh-remote: pairing error')
+        } catch {}
+      })
+      return
+    }
     forward(req, res).catch(() => {
       try {
         res.writeHead(502)

package/lib/index.js

@@ -16,7 +16,7 @@ import { start } from './supervisor.js'
 
 export const name = 'dsh-remote-hub'
 
-export const version = '0.1.0'
+export const version = '0.2.1'
 
 /** No host services are required: the plugin only needs Node builtins. */
 export const inject = []

package/lib/pairing-routes.js

@@ -0,0 +1,119 @@
+/**
+ * Pairing endpoints served by the bridge itself (never proxied to DSH).
+ *
+ *   GET  /_dsh-remote/pair          → HTML page with a QR code and the address text
+ *   GET  /_dsh-remote/pair.svg      → the same QR as a standalone SVG (for embedding)
+ *   POST /_dsh-remote/pair/redeem   → {code} → {publicUrl?, lanUrl, cookie, expiresAt}
+ *
+ * The QR payload is deliberately small and secret-free:
+ *   {"v":1,"u":"https://xxx.trycloudflare.com","c":"AB12CD34EF","e":1767000000000}
+ *
+ * @module lib/pairing-routes
+ */
+
+import QRCode from 'qrcode'
+
+export const PAIR_PREFIX = '/_dsh-remote/pair'
+
+/** Build the payload the phone parses. `u` is the URL the phone should talk to. */
+export function buildPairPayload({ url, code, expiresAt }) {
+  return JSON.stringify({ v: 1, u: url, c: code, e: expiresAt })
+}
+
+/**
+ * Handle a pairing request.
+ *
+ * @param {object} deps
+ * @param {import('node:http').IncomingMessage} deps.req
+ * @param {import('node:http').ServerResponse} deps.res
+ * @param {() => {url: string, cookie: string} | null} deps.current  latest URL + cookie
+ * @param {ReturnType<typeof import('./pairing').createPairingStore>} deps.store
+ * @returns {Promise<boolean>} true when the request was handled here
+ */
+export async function handlePairing({ req, res, current, store }) {
+  const url = String(req.url || '')
+  if (!url.startsWith(PAIR_PREFIX)) return false
+
+  const snapshot = current()
+  if (!snapshot) {
+    res.writeHead(503, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+    res.end(JSON.stringify({ ok: false, reason: 'not-ready' }))
+    return true
+  }
+
+  if (url === PAIR_PREFIX + '/redeem' && req.method === 'POST') {
+    let body = ''
+    await new Promise((resolve) => {
+      req.on('data', (chunk) => {
+        body += chunk
+        if (body.length > 4096) req.destroy()
+      })
+      req.on('end', resolve)
+      req.on('error', resolve)
+    })
+    let code = ''
+    try {
+      code = JSON.parse(body || '{}').code ?? ''
+    } catch {
+      /* fall through to the unknown-code branch */
+    }
+    const result = store.redeem(code)
+    if (!result.ok) {
+      res.writeHead(410, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(JSON.stringify({ ok: false, reason: result.reason }))
+      return true
+    }
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+    res.end(
+      JSON.stringify({
+        ok: true,
+        url: snapshot.url,
+        cookie: result.cookie,
+        issuedAt: result.issuedAt,
+      }),
+    )
+    return true
+  }
+
+  // Any other GET under the prefix hands out a fresh code.
+  const { code, expiresAt, ttlMs } = store.issue(snapshot.cookie)
+  const payload = buildPairPayload({ url: snapshot.url, code, expiresAt })
+
+  if (url === PAIR_PREFIX + '/svg') {
+    const svg = await QRCode.toString(payload, { type: 'svg', margin: 1, width: 320, errorCorrectionLevel: 'M' })
+    res.writeHead(200, { 'content-type': 'image/svg+xml; charset=utf-8', 'cache-control': 'no-store' })
+    res.end(svg)
+    return true
+  }
+
+  const svg = await QRCode.toString(payload, { type: 'svg', margin: 2, width: 360, errorCorrectionLevel: 'M' })
+  const minutes = Math.round(ttlMs / 60000)
+  const html = `<!doctype html>
+<html lang="zh"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>DSH Remote 配对</title>
+<style>
+  :root { color-scheme: light dark }
+  body { font: 15px/1.6 system-ui, -apple-system, "Segoe UI", sans-serif; margin: 0;
+         display: flex; min-height: 100vh; align-items: center; justify-content: center;
+         background: #0e1116; color: #e8eaed }
+  .card { background: #171b22; border: 1px solid #262c36; border-radius: 16px; padding: 28px 32px; text-align: center; max-width: 460px }
+  h1 { font-size: 18px; margin: 0 0 4px }
+  p  { margin: 6px 0; color: #9aa4b2; font-size: 13px }
+  .qr { background: #fff; padding: 12px; border-radius: 12px; display: inline-block; margin: 14px 0 10px }
+  code { background: #222835; padding: 2px 6px; border-radius: 5px; font-size: 13px; word-break: break-all }
+  .addr { font-size: 12px; color: #8b93a1; word-break: break-all; margin-top: 10px }
+  .ok { color: #6ee7a8 }
+</style></head>
+<body><div class="card">
+  <h1>用 DSH Remote 扫这个码</h1>
+  <p>配对码 <code>${code}</code> · ${minutes} 分钟内有效，且只能用一次</p>
+  <div class="qr">${svg}</div>
+  <p class="ok">扫码后自动填入地址并换取登录凭据</p>
+  <p class="addr">本页地址：<br>${snapshot.url}</p>
+  <p class="addr">手输备用：打开 App → 设置 → 扫码配对 → 输入配对码</p>
+</div></body></html>`
+  res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(html)
+  return true
+}

package/lib/pairing.js

@@ -0,0 +1,85 @@
+/**
+ * One-time pairing codes.
+ *
+ * The QR code the phone scans must never contain the 30-day cookie itself: a photo of the screen
+ * would hand out permanent access. Instead the QR carries a short random code with a 10 minute
+ * TTL, the bridge keeps code → cookie in memory, and redeeming burns the code.
+ *
+ * In-memory on purpose: a restart invalidates outstanding codes (fail safe), and nothing
+ * sensitive lands on disk.
+ *
+ * @module lib/pairing
+ */
+
+import { randomBytes } from 'node:crypto'
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000
+const MAX_ACTIVE = 20
+
+/** Crockford-ish alphabet: no look-alike characters, so codes can be read aloud or typed. */
+const ALPHABET = '23456789ABCDEFGHJKLMNPQRSTUVWXYZ'
+
+function randomCode(length = 10) {
+  const bytes = randomBytes(length)
+  let out = ''
+  for (let i = 0; i < length; i++) out += ALPHABET[bytes[i] % ALPHABET.length]
+  return out
+}
+
+export function createPairingStore({ ttlMs = DEFAULT_TTL_MS, max = MAX_ACTIVE } = {}) {
+  /** @type {Map<string, {cookie: string, expiresAt: number, createdAt: number}>} */
+  const codes = new Map()
+
+  function gc(now = Date.now()) {
+    for (const [code, entry] of codes) {
+      if (entry.expiresAt <= now) codes.delete(code)
+    }
+  }
+
+  /**
+   * Create a code bound to the current cookie.
+   *
+   * @param {string} cookie
+   * @returns {{code: string, expiresAt: number, ttlMs: number}}
+   */
+  function issue(cookie) {
+    gc()
+    // Drop the oldest entries when the store grows: a phone that scanned an old QR should not
+    // keep working forever just because we never expired it.
+    while (codes.size >= max) {
+      const oldest = codes.keys().next().value
+      codes.delete(oldest)
+    }
+    const now = Date.now()
+    const code = randomCode()
+    const expiresAt = now + ttlMs
+    codes.set(code, { cookie, expiresAt, createdAt: now })
+    return { code, expiresAt, ttlMs }
+  }
+
+  /**
+   * Exchange a code for its cookie. The code is consumed even when it has expired, so a leaked
+   * code cannot be retried after the first attempt.
+   *
+   * @param {string} code
+   * @returns {{ok: true, cookie: string, issuedAt: number} | {ok: false, reason: 'unknown'|'expired'}}
+   */
+  function redeem(code) {
+    if (typeof code !== 'string' || code.length === 0) return { ok: false, reason: 'unknown' }
+    const normalized = code.trim().toUpperCase()
+    const entry = codes.get(normalized)
+    if (!entry) return { ok: false, reason: 'unknown' }
+    codes.delete(normalized)
+    if (entry.expiresAt <= Date.now()) return { ok: false, reason: 'expired' }
+    return { ok: true, cookie: entry.cookie, issuedAt: entry.createdAt }
+  }
+
+  return {
+    issue,
+    redeem,
+    gc,
+    get size() {
+      return codes.size
+    },
+  }
+}

package/lib/supervisor.js

@@ -16,6 +16,7 @@ import path from 'node:path'
 import { startBridge } from './bridge.js'
 import { cookieExpiry, mintCookie } from './cookie.js'
 import { createDiscovery } from './discover.js'
+import { createPairingStore } from './pairing.js'
 import { startTunnel } from './tunnel.js'
 
 export const DATA_DIR = path.join(os.homedir(), '.dsh', 'dsh-remote')
@@ -159,10 +160,24 @@ export async function start(config = {}) {
   if (initialPort) log(`dsh-remote: upstream host on 127.0.0.1:${initialPort}`)
   else log('dsh-remote: no upstream host found yet; the bridge will keep retrying')
 
+  // Pairing: the QR carries a one-time code, not the cookie; redeeming burns it.
+  const pairingStore = createPairingStore()
+  const pairing = {
+    store: pairingStore,
+    // `current()` is read at redeem time so a URL that appears later (tunnel is still coming up)
+    // is still handed to the phone.
+    current: () => ({ url: lastPublicUrl ?? (ipForPairing ? `http://${ipForPairing}:${Number(port) || 6300}` : ''), cookie }),
+  }
+
+  const ipForPairing = lanAddress()
+  /** Public URL is filled in after the tunnel starts; pairing reads it lazily. */
+  let lastPublicUrl = null
+
   const bridge = await startBridge({
     listenPort: Number(port) || 6300,
     authority,
     upstream: discovery,
+    pairing,
     log,
   })
 
@@ -174,7 +189,8 @@ export async function start(config = {}) {
     log,
   })
 
-  const ip = lanAddress()
+  lastPublicUrl = tunnel.publicUrl
+  const ip = ipForPairing
   const status = {
     updatedAt: Date.now(),
     bridgePort: bridge.port,
@@ -184,6 +200,11 @@ export async function start(config = {}) {
     public: { url: tunnel.publicUrl, kind: tunnel.kind, ...(tunnel.note ? { note: tunnel.note } : {}) },
     cookie,
     cookieExpiresAt: expiresAt ?? cookieExpiry(cookie),
+    pairing: {
+      // Prefer the public URL: a phone on 4G cannot reach the LAN address.
+      url: tunnel.publicUrl ?? (ip ? `http://${ip}:${bridge.port}` : null),
+      page: `/_dsh-remote/pair`,
+    },
   }
   writeStatus(status)
 

package/lib/tunnel.js

@@ -56,10 +56,14 @@ function which(cmd) {
 
 /** Locate an installed tunel binary, or null. */
 export function findNgrok() {
+  const exe = process.platform === 'win32' ? 'ngrok.exe' : 'ngrok'
   const candidates = [
-    process.platform === 'win32' ? path.join(process.env.LOCALAPPDATA || '', 'ngrok', 'ngrok.exe') : null,
-    path.join(DATA_DIR, process.platform === 'win32' ? 'ngrok.exe' : 'ngrok'),
-    process.platform === 'win32' ? 'ngrok.exe' : 'ngrok',
+    process.platform === 'win32' ? path.join(process.env.LOCALAPPDATA || '', 'ngrok', exe) : null,
+    path.join(DATA_DIR, exe),
+    path.join(process.cwd(), 'tools', exe),
+    path.join(os.homedir(), 'Documents', 'DSH', 'DshRemote', 'tools', exe),
+    path.join(os.homedir(), 'Documents', 'DSH', '.dsh-apk-research', 'tools', exe),
+    exe,
   ].filter(Boolean)
   for (const c of candidates) {
     if (exists(c)) return c
@@ -69,7 +73,14 @@ export function findNgrok() {
 }
 
 export function findCloudflared() {
-  const candidates = [CLOUDFLARED_EXE, path.join(DATA_DIR, 'cloudflared.exe')]
+  const exe = process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared'
+  const candidates = [
+    CLOUDFLARED_EXE,
+    path.join(DATA_DIR, exe),
+    path.join(process.cwd(), 'tools', exe),
+    path.join(os.homedir(), 'Documents', 'DSH', 'DshRemote', 'tools', exe),
+    path.join(os.homedir(), 'Documents', 'DSH', '.dsh-apk-research', 'tools', exe),
+  ]
   for (const c of candidates) {
     if (exists(c)) return c
   }
@@ -144,6 +155,13 @@ export async function startTunnel({ kind = 'auto', bridgePort, authority, domain
   const wantCloudflared = kind === 'auto' || kind === 'cloudflared'
 
   if (wantNgrok) {
+    // A tunnel that is already pointing at this bridge (the usual case for a long-running setup
+    // with a static ngrok domain) is reused instead of spawning a second agent.
+    const reused = await existingNgrokUrl(bridgePort)
+    if (reused) {
+      log(`reusing the running ngrok tunnel: ${reused}`)
+      return { publicUrl: reused, kind: 'ngrok', close: () => {} }
+    }
     const ngrok = findNgrok()
     if (ngrok) {
       const args = ['http', String(bridgePort), '--host-header', authority, '--log', 'stdout', '--log-format', 'json']
@@ -178,6 +196,24 @@ export async function startTunnel({ kind = 'auto', bridgePort, authority, domain
   return { publicUrl: null, kind: 'none', close: () => {} }
 }
 
+/** Ask a running ngrok agent what it already exposes for `bridgePort`. */
+async function existingNgrokUrl(bridgePort) {
+  try {
+    const res = await fetch('http://127.0.0.1:4040/api/tunnels', { signal: AbortSignal.timeout(2000) })
+    if (!res.ok) return null
+    const doc = await res.json()
+    const tunnels = Array.isArray(doc?.tunnels) ? doc.tunnels : []
+    for (const t of tunnels) {
+      const addr = String(t?.config?.addr ?? '')
+      // ngrok reports the upstream as `http://localhost:6300` / `http://127.0.0.1:6300`.
+      if (new RegExp(`:${bridgePort}(/|$)`).test(addr)) return t.public_url || null
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
 function waitForUrl(child, timeoutMs) {
   return new Promise((resolve) => {
     let done = false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-hub",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "DSH 插件：把电脑上的 DeepSeek Harness 变成手机可访问的服务——起桥接、自动开隧道（ngrok / cloudflared）、签发 30 天 Cookie，并输出地址与凭据，配合 DSH Remote Android App 使用。",
   "type": "module",
   "main": "lib/index.js",
@@ -50,5 +50,8 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
   }
 }