@zmainer/dsh-wx-bridge 1.0.8

package/lib/kernel/keeper.mjs

@@ -0,0 +1,302 @@
+/**
+ * WeChat ⇄ DSH bridge keeper (零依赖).
+ *
+ * 职责：每 KEEPER_INTERVAL_MS 自检一次，不健康则以「脱离父进程树」的方式重新拉起桥。
+ * 健康判据：bridge.lock 的 pid 存活 + heartbeat.json 新鲜 + polls 在推进（按 boot 代次）。
+ *
+ * 全部路径与阈值走环境变量，无任何硬编码绝对路径：
+ *   BRIDGE_DATA    数据目录（必填；未给则回退 WXBRIDGE_DATA，再回退 $DSH_HOME/wxbridge）
+ *   BRIDGE_CWD     桥与任务的默认工作目录（默认 process.cwd()）
+ *   BRIDGE_NODE    node 可执行文件（默认 process.execPath）
+ *   KEEPER_INTERVAL_MS / KEEPER_STALE_MS  自检间隔 / 心跳判新阈值（默认 5 分钟）
+ *
+ * 也可作为模块被宿主进程 import：导出 tick()/status()/startBridge()/stopBridge()。
+ */
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, openSync, closeSync } from 'node:fs'
+import { spawn, execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const NL = String.fromCharCode(10)
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * 轮询是否在推进（纯函数，可单测）。
+ * 关键：进度下限必须按「桥的代次 boot」隔离——桥重启后 polls 归零，
+ * 若沿用上一代的下限，会被误判为「没进展」，导致每轮自检都杀掉重启（死循环）。
+ */
+export function progressVerdict(hb, floor, staleMs, now = Date.now()) {
+  if (!hb) return true
+  const sameBoot = floor && floor.polls >= 0 && Number(floor.boot) === Number(hb.boot)
+  if (!sameBoot) return true
+  if (hb.polls > floor.polls) return true
+  return !(now - (floor.seenAt || 0) > 2 * staleMs)
+}
+
+export function readConfigFile() {
+  const f = process.env.WXBRIDGE_CONFIG || join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'wxbridge', 'config.json')
+  try { return JSON.parse(readFileSync(f, 'utf8')) || {} } catch (e) {
+    if (e && e.code !== 'ENOENT') process.stderr.write('[keeper] config unreadable (' + String(e.message) + '): ' + f + NL)
+    return {}
+  }
+}
+
+export function resolveDataDir(explicit) {
+  const d = explicit || readConfigFile().dataDir || process.env.BRIDGE_DATA || process.env.WXBRIDGE_DATA
+    || join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'wxbridge')
+  return d
+}
+
+export function createKeeper(opts = {}) {
+  const file = readConfigFile()
+  const DATA = resolveDataDir(opts.dataDir)
+  const CWD = opts.cwd || file.cwd || process.env.BRIDGE_CWD || process.env.BRIDGE_ROOT || process.cwd()
+  const NODE = opts.node || process.env.BRIDGE_NODE || process.execPath
+
+
+  const INTERVAL_MS = Number(opts.intervalMs || file.intervalMs || process.env.KEEPER_INTERVAL_MS || 5 * 60 * 1000)
+  const STALE_MS = Number(opts.staleMs || file.staleMs || process.env.KEEPER_STALE_MS || 5 * 60 * 1000)
+  const BRIDGE = opts.bridgePath || join(HERE, 'bridge.mjs')
+  const BRIDGE_ARGS = Array.isArray(opts.bridgeArgs) ? opts.bridgeArgs : []
+  const VAULT = opts.vault || file.vault || process.env.BRAIN_VAULT || ''
+  // 宿主 home：给了它，桥的子进程就把会话写进宿主的会话仓库（手机对话在桌面工作区可见）
+  const HOST_HOME = opts.hostHome || file.hostHome || process.env.BRIDGE_HOST_HOME || ''
+  // 与应用同版本的运行时路径（让会话写成应用可读的 schema）
+  const DSH_BIN = opts.dshBin || file.dshBin || process.env.BRIDGE_DSH_BIN || ''
+  const DETACHED = opts.detached !== false
+  /**
+   * monitor = 只监测与报告，绝不 spawn / 杀进程（宿主半的默认）；
+   * heal    = 允许自愈（独立 keeper 的职责：脱树重启）。
+   * 原因：宿主内嵌的 keeper 若参与自愈，它拉起的桥就挂在宿主进程树里，
+   * 宿主被整树终止时桥会被连带杀掉（E-2026-09-21-06）。
+   */
+  const SUPERVISE = opts.superviseMode === 'heal' ? 'heal' : 'monitor'
+
+  const LOCK = join(DATA, 'bridge.lock')
+  const KEEPER_LOCK = join(DATA, 'keeper.lock')
+  const HB = join(DATA, 'heartbeat.json')
+  const POLL_STATE = join(DATA, 'keeper-polls.json')
+  const LOG = join(DATA, 'keeper.log')
+
+  mkdirSync(DATA, { recursive: true })
+
+  const log = (m) => {
+    try { appendFileSync(LOG, new Date().toISOString() + ' ' + m + NL) } catch {}
+  }
+  const childEnv = () => ({
+    ...process.env,
+    BRIDGE_DATA: DATA,
+    BRIDGE_CWD: CWD,
+    BRIDGE_ROOT: DATA,
+    ...(HOST_HOME ? { BRIDGE_HOST_HOME: HOST_HOME } : {}),
+    ...(DSH_BIN ? { BRIDGE_DSH_BIN: DSH_BIN } : {}),
+  })
+
+  const alive = (pid) => { try { process.kill(pid, 0); return true } catch { return false } }
+
+  function bridgePid() {
+    try {
+      if (!existsSync(LOCK)) return 0
+      const j = JSON.parse(readFileSync(LOCK, 'utf8'))
+      return Number(j?.pid) || 0
+    } catch { return 0 }
+  }
+
+  function readHeartbeat() {
+    try {
+      if (!existsSync(HB)) return null
+      const j = JSON.parse(readFileSync(HB, 'utf8'))
+      const at = Date.parse(j.at)
+      const ok = Number.isFinite(at) ? at : 0
+      return { at: ok, boot: Number(j.boot) || 0, polls: Number(j.polls) || 0, phase: j.phase, tasks: Number(j.tasks) || 0, age: Date.now() - ok }
+    } catch { return null }
+  }
+
+  const loadPollFloor = () => { try { return JSON.parse(readFileSync(POLL_STATE, 'utf8')) } catch { return { boot: 0, polls: -1, seenAt: 0 } } }
+  const savePollFloor = (v) => { try { writeFileSync(POLL_STATE, JSON.stringify(v)) } catch {} }
+
+  /**
+   * 拉起桥。detached=false 时桥会成为调用者（宿主）的后代 —— 宿主被整树终止就会连带杀掉桥，
+   * 所以「宿主半的常驻守护」必须用 detached=true，只有「一次性前台探测」才用 false。
+   */
+  function spawnBridge(detached = true) {
+    const extra = [...BRIDGE_ARGS,
+      ...(VAULT ? ['--vault', VAULT] : []),
+      ...(HOST_HOME ? ['--host-home', HOST_HOME] : []),
+      ...(DSH_BIN ? ['--dsh-bin', DSH_BIN] : [])]
+    // 桥的输出必须留档：原来 stdio:'ignore' → 起不来时**一个字都看不到**，
+    // 面板只能显示一个刚打印的 pid（2026-09-21 其他用户"启动不了"的排障黑洞）。
+    let fd = 'ignore'
+    const logFile = join(DATA, 'bridge-standalone.log')
+    // 每次启动写一条分隔线：时间 + kernel 版本 + 关键参数。
+    // 没有它，追加式日志会把"上一次的崩溃"混进"这一次的输出"，用户会误读（2026-09-21 实况）。
+    try {
+      mkdirSync(DATA, { recursive: true })
+      let ver = '?'
+      try { ver = JSON.parse(readFileSync(join(HERE, '..', '..', 'package.json'), 'utf8')).version || '?' } catch {}
+      const sep = '===== bridge start ' + new Date().toISOString() + ' pid_parent=' + process.pid +
+        ' ver=' + ver + ' data=' + DATA + ' cwd=' + CWD + ' detached=' + detached + ' ====='
+      appendFileSync(logFile, '\n' + sep + '\n')
+      fd = openSync(logFile, 'a')
+    } catch (e) {
+      // 出声：这里失败会让"桥为什么起不来"重新变成黑洞，绝不能静默（与 L3 E-2026-09-21-16/20 同族）
+      console.error('[keeper] 写 bridge-standalone.log 失败：' + String(e && e.message ? e.message : e))
+    }
+    const child = spawn(NODE, [BRIDGE, ...extra], { cwd: CWD, env: childEnv(), detached, stdio: ['ignore', fd, fd], windowsHide: true })
+    if (typeof fd === 'number') { try { closeSync(fd) } catch {} }
+    if (detached) child.unref()
+    return child.pid
+  }
+
+  function killTree(pid) {
+    try { execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' }) } catch {}
+  }
+
+  function cleanOrphans(deadPid) {
+    let killed = 0
+    try {
+      const ps = 'Get-CimInstance Win32_Process -Filter ' + JSON.stringify("name='node.exe'")
+        + ' | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress'
+      const out = execFileSync('powershell.exe', ['-NoProfile', '-Command', ps], { encoding: 'utf8', windowsHide: true, timeout: 20000 })
+      const parsed = JSON.parse(out || '[]')
+      const list = Array.isArray(parsed) ? parsed : [parsed]
+      for (const it of list) {
+        const cmd = String(it.CommandLine || '')
+        if (!cmd.includes('dsh/lib/bin.js')) continue
+        if (!cmd.toUpperCase().includes(DATA.toUpperCase())) continue
+        if (deadPid && Number(it.ProcessId) === Number(deadPid)) continue
+        try { execFileSync('taskkill', ['/PID', String(it.ProcessId), '/T', '/F'], { windowsHide: true, stdio: 'ignore' }); killed++ } catch {}
+      }
+    } catch {}
+    return killed
+  }
+
+  function status() {
+    const pid = bridgePid()
+    const hb = readHeartbeat()
+    const pidOk = pid > 0 && alive(pid)
+    const fresh = !!hb && hb.age < STALE_MS
+    return { pid, pidOk, fresh, heartbeat: hb, staleMs: STALE_MS, intervalMs: INTERVAL_MS, dataDir: DATA, cwd: CWD }
+  }
+
+  /**
+   * 人工停止意图（粘性）：写进 state.json 的 manualStop 字段。
+   * 没有它，「停止」按钮形同虚设——下一次自检（≤5 分钟）就会把桥拉回来。
+   * 只有显式 start 才清除。
+   */
+  const readManualStop = () => {
+    try {
+      const s = JSON.parse(readFileSync(join(DATA, 'state.json'), 'utf8'))
+      const m = s && s.manualStop
+      return m && m.at ? m : null
+    } catch { return null }
+  }
+  const writeManualStop = (v) => {
+    try {
+      let s = {}
+      try { s = JSON.parse(readFileSync(join(DATA, 'state.json'), 'utf8')) || {} } catch { s = {} }
+      if (v) s.manualStop = v; else delete s.manualStop
+      // 必须重算 checksum：桥的 loadState() 校验不过会把整份 state 当成篡改隔离（丢会话记忆）
+      const c = { ...s }
+      delete c.checksum
+      s.checksum = createHash('sha256').update(JSON.stringify(c)).digest('hex')
+      writeFileSync(join(DATA, 'state.json'), JSON.stringify(s, null, 1))
+    } catch (e) { log('manualStop write failed: ' + String(e?.message ?? e)) }
+  }
+
+  function stopBridge(reason) {
+    const pid = bridgePid()
+    let stopped = false
+    if (pid > 0) { killTree(pid); if (alive(pid)) { try { process.kill(pid) } catch {} } stopped = true }
+    try { cleanOrphans(pid) } catch {}
+    try { writeFileSync(LOCK, '{}') } catch {}
+    try { writeFileSync(HB, JSON.stringify({ at: new Date().toISOString(), phase: 'stopped', polls: 0, tasks: 0, pid: 0, boot: 0 })) } catch {}
+    writeManualStop({ at: new Date().toISOString(), by: reason || 'user' })
+    log('stopped by request pid=' + pid + (reason ? ' by=' + reason : ''))
+    return stopped
+  }
+
+  /** 显式启动：清除人工停止意图，再拉起。 */
+  function startBridgeNow(reason, detached = true) {
+    writeManualStop(null)
+    const pid = spawnBridge(detached)
+    log('started by request pid=' + pid + (reason ? ' by=' + reason : ''))
+    return pid
+  }
+
+  function tick() {
+    const pid = bridgePid()
+    const hb = readHeartbeat()
+    const pidOk = pid > 0 && alive(pid)
+    const fresh = !!hb && hb.age < STALE_MS
+
+    // 人工停止意图优先：不自愈，直到用户显式 start
+    const manual = readManualStop()
+    if (manual && !pidOk) {
+      return { restarted: false, healthy: false, manualStop: manual }
+    }
+
+    let progressing = true
+    if (hb) {
+      const floor = loadPollFloor()
+      progressing = progressVerdict(hb, floor, STALE_MS)
+      if (progressing) {
+        if (floor.polls < 0 || Number(floor.boot) !== Number(hb.boot) || hb.polls > floor.polls) {
+          savePollFloor({ boot: hb.boot, polls: hb.polls, seenAt: Date.now() })
+        }
+      }
+    }
+
+    if (pidOk && fresh && progressing) {
+      return { restarted: false, healthy: true }
+    }
+
+    log('UNHEALTHY pid=' + pid + ' pidOk=' + pidOk + ' fresh=' + fresh + ' progressing=' + progressing
+      + ' age=' + (hb ? Math.round(hb.age / 1000) + 's' : 'n/a') + ' polls=' + (hb ? hb.polls : 'n/a')
+      + ' mode=' + SUPERVISE)
+    if (SUPERVISE === 'monitor') {
+      // 宿主半只报告：不杀、不拉。生命周期归独立 keeper（E-2026-09-21-06）。
+      return { restarted: false, healthy: false, monitored: true, pid }
+    }
+    const killed = cleanOrphans(pid)
+    if (killed) log('cleaned orphan headless children = ' + killed)
+    if (pidOk) { killTree(pid); if (alive(pid)) { try { process.kill(pid) } catch {} } log('killed pid=' + pid) }
+    try { writeFileSync(LOCK, '{}') } catch {}
+    let newPid = 0
+    try { newPid = spawnBridge(DETACHED); log('restart spawned pid=' + newPid + ' detached=' + DETACHED) } catch (e) { log('restart FAILED: ' + String(e?.message ?? e)) }
+    return { restarted: true, healthy: false, pid: newPid }
+  }
+
+  function acquireKeeperLock() {
+    try {
+      if (existsSync(KEEPER_LOCK)) {
+        const old = JSON.parse(readFileSync(KEEPER_LOCK, 'utf8'))
+        if (old && old.pid && alive(old.pid)) { log('keeper already running pid=' + old.pid + ' -> exit'); return false }
+      }
+    } catch {}
+    writeFileSync(KEEPER_LOCK, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }))
+    const release = () => { try { writeFileSync(KEEPER_LOCK, '{}') } catch {} }
+    process.on('exit', release)
+    process.on('SIGINT', () => { release(); process.exit(0) })
+    process.on('SIGTERM', () => { release(); process.exit(0) })
+    return true
+  }
+
+  function run() {
+    if (!acquireKeeperLock()) process.exit(0)
+    log('keeper start pid=' + process.pid + ' data=' + DATA + ' interval=' + Math.round(INTERVAL_MS / 1000) + 's bridge=' + BRIDGE)
+    tick()
+    setInterval(tick, INTERVAL_MS)
+  }
+
+  return { run, tick, status, startBridge: startBridgeNow, spawnBridge, stopBridge, log, superviseMode: SUPERVISE, hostHome: HOST_HOME, dshBin: DSH_BIN, dataDir: DATA, cwd: CWD, bridgePath: BRIDGE, intervalMs: INTERVAL_MS, staleMs: STALE_MS, manualStop: readManualStop }
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]
+if (isMain) {
+  const argOf = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 ? process.argv[i + 1] : d }
+  const keeper = createKeeper({ dataDir: argOf('--data-dir'), cwd: argOf('--cwd'), intervalMs: argOf('--interval-ms'), superviseMode: 'heal' })
+  keeper.run()
+}

package/lib/kernel/second-brain-contract.txt

@@ -0,0 +1,7 @@
+You are the assistant behind this chat channel, powered by the {{model}} model. Your working directory is {{cwd}}.
+
+# 通道固定提示词（模板 · 可改可清空）
+# - 这段文字（若填写）会作为「固定身份」拼在每条手机任务前面；**留空则不加任何前缀**，
+#   直接把用户原话交给 DSH，由 DSH 自己的组合 / 预设 / 技能 / 工作区决定身份。
+# - 占位符：{{model}} 模型名 ｜ {{cwd}} 工作区 ｜ {{vault}} 知识库路径（可选配置）
+# - 本文件是**模板**：面板里保存后写入数据目录的副本，改这里不影响已保存的配置。

package/lib/pairing.js

@@ -0,0 +1,225 @@
+/**
+ * 扫码配对（iLink ClawBot）：宿主半持有配对会话，客户端只做展示与轮询。
+ *
+ * 协议（实测自 @local/dsh-weixin 的 IlinkClient）：
+ *   POST ilink/bot/get_bot_qrcode?bot_type=3     body {local_token_list:[...]}  → {qrcode, qrcode_img_content}
+ *   GET  ilink/bot/get_qrcode_status?qrcode=…[&verify_code=…]                    → {status, …}
+ *   status: wait | scaned | need_verifycode | scaned_but_redirect | binded_redirect | expired | confirmed
+ *   confirmed 返回 {bot_token, ilink_bot_id, ilink_user_id, baseurl}
+ *
+ * 产出：bot_token 写进凭据文件（merge 语义，保留其它 refs）；state.json 登记 owner 与账号。
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join, dirname } from 'node:path'
+
+const NL = String.fromCharCode(10)
+const API_BASE = process.env.ILINK_BASE || 'https://ilinkai.weixin.qq.com'
+const BOT_TYPE = '3'
+const CRED_REF = 'DSH_WEIXIN_BOT_TOKEN'
+
+const headers = () => ({
+  'content-type': 'application/json',
+  'iLink-App-Id': 'bot',
+  'iLink-App-ClientVersion': String((2 << 16) | (4 << 8) | 6),
+})
+
+const post = async (url, body, timeoutMs = 15000) => {
+  const ctl = new AbortController(); const t = setTimeout(() => ctl.abort(), timeoutMs)
+  try {
+    const res = await fetch(url, { method: 'POST', headers: headers(), body: JSON.stringify(body ?? {}), signal: ctl.signal })
+    const raw = await res.text()
+    if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + raw.slice(0, 200))
+    return JSON.parse(raw)
+  } finally { clearTimeout(t) }
+}
+
+const get = async (url, timeoutMs = 35000) => {
+  const ctl = new AbortController(); const t = setTimeout(() => ctl.abort(), timeoutMs)
+  try {
+    const res = await fetch(url, { method: 'GET', headers: headers(), signal: ctl.signal })
+    const raw = await res.text()
+    if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + raw.slice(0, 200))
+    return JSON.parse(raw)
+  } finally { clearTimeout(t) }
+}
+
+function readTokenFromFile(credFile) {
+  try {
+    const m = readFileSync(credFile, 'utf8').match(new RegExp('^\\s*' + CRED_REF + ':\\s*(.+)$', 'm'))
+    return m ? m[1].trim().replace(/^["']|["']$/g, '') : ''
+  } catch { return '' }
+}
+
+/** merge 写入凭据：只增改目标 ref，保留其它 refs、顶层键与夹层注释（原子写）。 */
+export function writeCredentialRef(credFile, ref, value) {
+  const hadFile = existsSync(credFile)
+  const lines = hadFile ? readFileSync(credFile, 'utf8').split(/\r?\n/) : []
+  const refRe = /^\s{2}([A-Za-z_][A-Za-z0-9_]*):(\s*)(.*)$/
+  const head = []
+  const entries = []
+  const tail = []
+  let inRefs = false, refsSeen = false, refsClosed = false
+  for (const line of lines) {
+    if (/^refs:\s*$/.test(line)) { inRefs = true; refsSeen = true; head.push(line); continue }
+    if (inRefs && refRe.test(line)) { entries.push(line); continue }
+    if (inRefs) { inRefs = false; refsClosed = true }
+    if (refsClosed) tail.push(line)
+    else head.push(line)
+  }
+
+  let replaced = false
+  const outEntries = entries.map((l) => {
+    const m = l.match(refRe)
+    if (m && m[1] === ref) { replaced = true; return '  ' + ref + ': ' + value }
+    return l
+  })
+  if (!replaced) outEntries.push('  ' + ref + ': ' + value)
+
+  const headTrim = head.slice()
+  while (headTrim.length && headTrim[headTrim.length - 1].trim() === '') headTrim.pop()
+  const tailTrim = tail.slice()
+  while (tailTrim.length && tailTrim[tailTrim.length - 1].trim() === '') tailTrim.pop()
+
+  const parts = []
+  if (!refsSeen) parts.push('refs:')
+  parts.push(...headTrim)
+  parts.push(...outEntries)
+  if (tailTrim.length) parts.push(...tailTrim)
+
+  mkdirSync(dirname(credFile), { recursive: true })
+  const tmp = credFile + '.tmp'
+  writeFileSync(tmp, parts.join(NL) + NL, 'utf8')
+  renameSync(tmp, credFile)
+  return true
+}
+
+/** 把 owner/账号写进桥的 state.json（保持 checksum 一致，原子写）。 */
+export function seedState(stateFile, { userId, accountId, baseUrl, addOwner, dropOthers, cwd }) {
+  let s = {}
+  try { s = JSON.parse(readFileSync(stateFile, 'utf8')) || {} } catch { s = {} }
+  s.peers ||= {}; s.allowedUsers ||= []; s.tasks ||= {}; s.processed ||= []
+  if (dropOthers && userId) {
+    // 换了绑定账号：清掉旧主人，避免旧账号仍能驱动这台机器
+    s.allowedUsers = []
+    s.peers = {}
+  }
+  if (userId && (addOwner || s.allowedUsers.length === 0) && !s.allowedUsers.includes(userId)) s.allowedUsers.push(userId)
+  if (userId) s.peers[userId] ||= { cwd: cwd || '', history: [], approvals: [] }
+  s.account = { accountId: accountId || null, userId: userId || null, baseUrl: baseUrl || API_BASE, connectedAt: new Date().toISOString() }
+  const c = { ...s }; delete c.checksum
+  s.checksum = createHash('sha256').update(JSON.stringify(c)).digest('hex')
+  mkdirSync(dirname(stateFile), { recursive: true })
+  const tmp = stateFile + '.tmp'
+  writeFileSync(tmp, JSON.stringify(s, null, 1), 'utf8')
+  renameSync(tmp, stateFile)
+  return { allowedUsers: s.allowedUsers.length, account: s.account, registered: userId ? s.allowedUsers.includes(userId) : false }
+}
+
+/**
+ * 创建一次配对会话。toDataUrl 由调用方注入（宿主半用 profile 里的 qrcode 包）。
+ */
+export function createPairing(opts) {
+  const dataDir = opts.dataDir
+  const dshHome = opts.dshHome || process.env.DSH_HOME
+  const credFile = opts.credFile || join(dshHome || join(dataDir, 'dsh-home'), '.credentials.yaml')
+  const stateFile = join(dataDir, 'state.json')
+  const toDataUrl = opts.toDataUrl
+  const log = opts.log || (() => {})
+
+  let session = null
+
+  const status = () => {
+    if (!session) return { active: false }
+    return {
+      active: true, status: session.status, qrcode: session.qrcode, qrDataUrl: session.qrDataUrl,
+      qrContent: session.qrContent || null,
+      needsVerifyCode: session.status === 'need_verifycode', verifyCodeTried: !!session.verifyCode,
+      startedAt: session.startedAt, expiredAt: session.expiresAt, error: session.error || null,
+      confirmed: session.confirmed || null, redirectHost: session.redirectHost || null,
+    }
+  }
+
+  const finish = (resp) => {
+    const token = resp.bot_token
+    const userId = resp.ilink_user_id
+    const accountId = resp.ilink_bot_id
+    const baseUrl = resp.baseurl || API_BASE
+    writeCredentialRef(credFile, CRED_REF, token)
+    // 扫码的人就是新主人：直接登记进白名单（否则换号后消息会被"未登记"丢弃，
+    // 还得再手工发一次登记口令 —— 这一步是 2026-09-21 换号踩坑后补的）。
+    const seeded = seedState(stateFile, { userId, accountId, baseUrl, addOwner: true, dropOthers: true })
+    session.status = 'confirmed'
+    session.confirmed = {
+      accountId, userId, baseUrl, credentialFile: credFile,
+      allowedUsers: seeded.allowedUsers, registered: seeded.registered,
+    }
+    log('pair-confirmed account=' + accountId + ' user=' + String(userId).slice(0, 12)
+        + ' cred=' + credFile + ' registered=' + seeded.registered)
+  }
+
+  const refreshQr = async () => {
+    const localTokens = []
+    const t = readTokenFromFile(credFile) || process.env.DSH_WEIXIN_BOT_TOKEN
+    if (t) localTokens.push(t)
+    const qr = await post(API_BASE + '/ilink/bot/get_bot_qrcode?bot_type=' + BOT_TYPE, { local_token_list: localTokens })
+    if (!qr || !qr.qrcode || !qr.qrcode_img_content) throw new Error('网关没有返回有效二维码')
+    session.qrcode = qr.qrcode
+    session.pollBase = API_BASE
+    session.verifyCode = undefined
+    session.qrDataUrl = toDataUrl ? await toDataUrl(qr.qrcode_img_content) : null
+    session.qrContent = qr.qrcode_img_content
+    session.status = 'wait'
+    session.error = null
+    session.startedAt = new Date().toISOString()
+    session.expiresAt = new Date(Date.now() + 120000).toISOString()
+    session.confirmed = null
+    log('pair-qr-issued qrcode=' + qr.qrcode)
+  }
+
+  /**
+   * 客户端每 ~2.5s 调一次；内部单飞（single-flight）：
+   * 网关的 get_qrcode_status 是 ~35s 长轮询，若并发发起会堆积 → 同一时刻只允许一次在途请求，
+   * 后来的调用直接复用同一个 promise。
+   */
+  let inflight = null
+  const pollOnce = async () => {
+    if (!session) return { active: false }
+    try {
+      let base = session.pollBase || API_BASE
+      if (session.redirectHost) base = 'https://' + session.redirectHost
+      let url = base + '/ilink/bot/get_qrcode_status?qrcode=' + encodeURIComponent(session.qrcode)
+      if (session.verifyCode) url += '&verify_code=' + encodeURIComponent(session.verifyCode)
+      const r = await get(url, 40000)
+      const st = r.status || 'wait'
+      if (st === 'confirmed') { finish(r); return status() }
+      if (st === 'expired') { await refreshQr(); return status() }
+      if (st === 'scaned_but_redirect' && r.redirect_host) session.redirectHost = r.redirect_host
+      if (st === 'binded_redirect') { session.status = 'binded_redirect'; session.error = '该 ClawBot 已绑定；如需重新配对，请先在原绑定端解除' }
+      else session.status = st
+      if (st === 'scaned') session.verifyCode = undefined
+      if (st !== 'binded_redirect') session.error = null
+    } catch (e) {
+      const msg = String(e?.message ?? e)
+      session.error = /abort/i.test(msg) ? null : msg
+    }
+    return status()
+  }
+
+  const poll = () => {
+    if (!session) return Promise.resolve({ active: false })
+    if (session.status === 'confirmed' || session.status === 'binded_redirect') return Promise.resolve(status())
+    if (inflight) return inflight
+    inflight = pollOnce().finally(() => { inflight = null })
+    return inflight
+  }
+
+  return {
+    start: async () => { session = { startedAt: new Date().toISOString() }; await refreshQr(); return status() },
+    poll,
+    status,
+    setVerifyCode: (code) => { if (!session) return { active: false }; session.verifyCode = String(code || '').trim() || undefined; return status() },
+    stop: () => { const was = !!session; session = null; return { active: false, stopped: was } },
+    credentialFile: credFile,
+  }
+}

package/lib/vendor/qr-svg.cjs

@@ -0,0 +1,58 @@
+/**
+ * 自带二维码渲染（零外部依赖）—— 给「微信连接」面板出配对二维码。
+ *
+ * 为什么自带：插件此前靠 `require.resolve('qrcode')` 在用户 profile 里找那个包，
+ * 而插件本身 `dependencies` 为空 —— 干净安装的机器根本没有它，面板就只剩"备用链接"
+ * （2026-09-21 其他用户实测反馈）。
+ *
+ * 组成：
+ *   - `qrcode-core/`：从 `qrcode@1.5.4`（MIT，Copyright (c) 2012 Ryan Day）原样复制的**编码核心**，
+ *     零外部依赖（只互相 require）；见同目录 LICENSE 与 NOTICE.md。
+ *   - 本文件：只用核心产出模块矩阵，然后自己画 **SVG**（省掉 pngjs/yargs 等依赖与 PNG 编码）。
+ *
+ * 输出是 `data:image/svg+xml;base64,…`，可直接喂给 `<img src>`（Chromium 正常渲染）。
+ */
+const QRCode = require('./qrcode-core/qrcode')
+
+/** 取模块矩阵：{size, get(r,c)}。 */
+function modules(text, ecLevel) {
+  const qr = QRCode.create(String(text), { errorCorrectionLevel: ecLevel || 'M' })
+  const size = qr.modules.size
+  const data = qr.modules.data
+  return {
+    size,
+    get: (r, c) => !!data[r * size + c],
+    version: qr.version,
+    ecLevel: qr.errorCorrectionLevel && qr.errorCorrectionLevel.bit !== undefined ? qr.errorCorrectionLevel.bit : null,
+    maskPattern: qr.maskPattern,
+  }
+}
+
+/**
+ * 渲染成 SVG data URL。
+ * @param {string} text 要编码的内容（配对时是微信返回的二维码内容）
+ * @param {{size?:number, margin?:number, ecLevel?:string}} [opts] size=目标边长(px)，margin=静默区格数
+ */
+function toSvgDataUrl(text, opts) {
+  const o = opts || {}
+  const m = modules(text, o.ecLevel)
+  const margin = o.margin === undefined ? 2 : o.margin
+  const target = o.size || 320
+  const scale = Math.max(1, Math.floor(target / (m.size + margin * 2)))
+  const px = (m.size + margin * 2) * scale
+  const rects = []
+  for (let r = 0; r < m.size; r++) {
+    for (let c = 0; c < m.size; c++) {
+      if (m.get(r, c)) {
+        rects.push('<rect x="' + ((c + margin) * scale) + '" y="' + ((r + margin) * scale) + '" width="' + scale + '" height="' + scale + '"/>')
+      }
+    }
+  }
+  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="' + px + '" height="' + px + '" ' +
+    'shape-rendering="crispEdges" viewBox="0 0 ' + px + ' ' + px + '">' +
+    '<rect width="' + px + '" height="' + px + '" fill="#ffffff"/>' +
+    '<g fill="#000000">' + rects.join('') + '</g></svg>'
+  return 'data:image/svg+xml;base64,' + Buffer.from(svg, 'utf8').toString('base64')
+}
+
+module.exports = { toSvgDataUrl, modules }

package/lib/vendor/qrcode-core/LICENSE

@@ -0,0 +1,10 @@
+The MIT License (MIT)
+
+Copyright (c) 2012 Ryan Day
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/lib/vendor/qrcode-core/NOTICE.md

@@ -0,0 +1,21 @@
+# 来源与许可 / Provenance
+
+本目录是 **`qrcode@1.5.4` 的编码核心**原样复制（未修改），来源包：
+
+- npm：`qrcode@1.5.4`（MIT）
+- 作者/版权：Copyright (c) 2012 Ryan Day（见同目录 `LICENSE`）
+- 复制范围：该包的 `lib/core/*.js`（编码核心，**零外部依赖**，只互相 require）
+- 未复制：`lib/renderer/*`、`bin/*`、`server.js` 等（依赖 `pngjs` / `yargs`，本插件不需要）
+
+用途：插件自己的 `lib/vendor/qr-svg.cjs` 调用这里的 `qrcode.js` 得到模块矩阵，
+再自行渲染成 SVG data URL，从而**不依赖用户环境里是否装有 `qrcode` 包**。
+
+此外还复制了 **`dijkstrajs@1.0.3`（MIT）** 的 `dijkstra.js` → 本目录 `dijkstrajs.js`
+（`segments.js` 用它做最优分段；许可见 `dijkstrajs.LICENSE`）。
+
+**唯一一处对 vendored 代码的改动**：`segments.js` 里 `require('dijkstrajs')` → `require('./dijkstrajs')`。
+原因：npm 打包默认忽略 `node_modules/`，把依赖放进 `lib/vendor/node_modules/` 会在发布包里丢掉
+（等于重演"干净安装缺依赖"）。改相对路径后所有文件都在包内、零外部解析。
+
+许可合规：MIT 允许复制与再分发，条件是保留版权与许可声明——`LICENSE`（qrcode）与
+`dijkstrajs.LICENSE` 已随本目录一起分发；插件的 `README.md`「许可」一节也注明了这些第三方代码。