@wanghaopeng1148/deskpet 2.0.0

package/server/services/wechat-bot.ts

@@ -0,0 +1,744 @@
+/**
+ * 微信 Bot — iLink Bot API 移植（对齐旧版 wechat_bot.py 44KB）
+ *
+ * 能力: 扫码登录(二维码自动刷新) / sendmessage 文本推送(自动拆条) /
+ *       getupdates 长轮询(收消息+维持 context_token) / 会话过期自动重连 / 看门狗
+ *
+ * 协议要点（实测经验，勿改）:
+ *  - 文本项不渲染 \n，用垂直制表符 \u000b 作为换行符
+ *  - ret/errcode == -14 表示会话过期，需重连
+ *  - context_token 只能靠用户主动发消息刷新，机器人无法主动续期
+ */
+import { EventEmitter } from 'node:events'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import type { WechatSettings } from '../../shared/types.ts'
+
+// ── 协议常量 ────────────────────────────────────────────────
+
+const ILINK_BASE_URL = 'https://ilinkai.weixin.qq.com'
+const CHANNEL_VERSION = '2.2.0'
+const ILINK_APP_CLIENT_VERSION = (2 << 16) | (2 << 8) | 0 // 131584
+
+const LONG_POLL_TIMEOUT_MS = 40_000
+const API_TIMEOUT_MS = 15_000
+const QR_FETCH_TIMEOUT_MS = 30_000
+const QR_POLL_INTERVAL_MS = 1_000
+const QR_EXPIRE_MAX = 3
+const QR_LOGIN_TIMEOUT_MS = 300_000
+const MSG_MAX_CHARS = 1800
+
+const HEARTBEAT_CHECK_INTERVAL_MS = 60_000
+const HEARTBEAT_STALE_THRESHOLD_MS = 120_000
+const MAX_RECONNECT_ATTEMPTS = 3
+const RECONNECT_DELAY_MS = 5_000
+
+export type WechatLoginStatus =
+  | 'idle'
+  | 'fetching'
+  | 'waiting'
+  | 'scanned'
+  | 'refreshed'
+  | 'confirmed'
+  | 'failed'
+  | 'cancelled'
+  | 'timeout'
+
+export const LOGIN_STATUS_TEXT: Record<WechatLoginStatus, string> = {
+  idle: '未连接',
+  fetching: '正在获取二维码…',
+  waiting: '请用微信扫描二维码',
+  scanned: '已扫码，请在手机上确认',
+  refreshed: '二维码已过期，已自动刷新',
+  confirmed: '已连接微信',
+  failed: '连接失败',
+  cancelled: '已取消',
+  timeout: '扫码超时，请重试'
+}
+
+  /** iLink Bot 凭据与会话状态（持久化到 userData/config/wechat.json） */
+export interface WechatCredentials {
+  botToken: string
+  botId: string
+  userId: string
+  /** 最近发消息的用户 → 推送目标 */
+  pushTarget: string
+  /** 用户 → 最近 context_token（推送会话凭证） */
+  contextTokens: Record<string, string>
+  /** 用户 → context_token 捕获时间戳（用于判断 24h 有效期） */
+  contextTokenTs: Record<string, number>
+  syncBuf: string
+  conversationConfirmed: boolean
+  linkedAt: string
+  baseUrl: string
+}
+
+function emptyCredentials(): WechatCredentials {
+  return {
+    botToken: '',
+    botId: '',
+    userId: '',
+    pushTarget: '',
+    contextTokens: {},
+    contextTokenTs: {},
+    syncBuf: '',
+    conversationConfirmed: false,
+    linkedAt: '',
+    baseUrl: ILINK_BASE_URL
+  }
+}
+
+export interface WechatStatus {
+  status: WechatLoginStatus
+  statusText: string
+  connected: boolean
+  sessionAlive: boolean
+  listening: boolean
+  botId: string
+  pushTarget: string
+  linkedAt: string
+  qrContent: string | null
+}
+
+/** fetch 注入点（测试替身） */
+export type FetchLike = (url: string, init?: { method?: string; headers?: Record<string, string>; body?: string; signal?: AbortSignal }) => Promise<{ ok: boolean; status: number; json: () => Promise<unknown> }>
+
+/** 拆条：超长消息按段落/长度切分 */
+export function splitMessage(text: string, maxChars = MSG_MAX_CHARS): string[] {
+  if (text.length <= maxChars) return [text]
+  const chunks: string[] = []
+  let current = ''
+  for (const line of text.split('\n')) {
+    if ((current + line + '\n').length > maxChars && current) {
+      chunks.push(current.trimEnd())
+      current = ''
+    }
+    if (line.length > maxChars) {
+      // 单行超长硬切
+      for (let i = 0; i < line.length; i += maxChars) {
+        chunks.push(line.slice(i, i + maxChars))
+      }
+    } else {
+      current += line + '\n'
+    }
+  }
+  if (current.trim()) chunks.push(current.trimEnd())
+  return chunks
+}
+
+/** 提取文本消息内容（item_list → text_item.text） */
+export function extractText(msg: Record<string, unknown>): string {
+  const items = msg['item_list'] as Array<Record<string, unknown>> | undefined
+  if (!Array.isArray(items)) return ''
+  const parts: string[] = []
+  for (const item of items) {
+    const textItem = item['text_item'] as Record<string, unknown> | undefined
+    const t = textItem?.['text']
+    if (typeof t === 'string' && t.trim()) parts.push(t.trim())
+  }
+  return parts.join('\n')
+}
+
+export class WechatBot extends EventEmitter {
+  private creds: WechatCredentials = emptyCredentials()
+  private loginStatus: WechatLoginStatus = 'idle'
+  private loginAbort: AbortController | null = null
+  private listenStop = false
+  private listening = false
+  private sessionAlive = false
+  private lastPollAt = 0
+  private reconnectAttempts = 0
+  private watchdog: ReturnType<typeof setInterval> | null = null
+  private commandHandler: ((text: string) => string | null) | null = null
+  /** 当前登录二维码内容（供 UI 渲染） */
+  private qrContent: string | null = null
+  private readonly fetchImpl: FetchLike
+  private credsPath: string
+  private getSettings: () => WechatSettings
+
+  constructor(credsPath: string, getSettings: () => WechatSettings, fetchImpl?: FetchLike) {
+    super()
+    this.credsPath = credsPath
+    this.getSettings = getSettings
+    this.fetchImpl = fetchImpl ?? (fetch as unknown as FetchLike)
+    this.load()
+  }
+
+  // ── 凭据持久化 ──────────────────────────────────────────
+
+  private load(): void {
+    try {
+      if (!existsSync(this.credsPath)) return
+      const raw = JSON.parse(readFileSync(this.credsPath, 'utf-8')) as Record<string, unknown>
+      this.creds = {
+        botToken: String(raw['bot_token'] ?? ''),
+        botId: String(raw['bot_id'] ?? ''),
+        userId: String(raw['user_id'] ?? ''),
+        pushTarget: String(raw['push_target'] ?? ''),
+        contextTokens: (raw['context_tokens'] as Record<string, string>) ?? {},
+        contextTokenTs: (raw['context_token_ts'] as Record<string, number>) ?? {},
+        syncBuf: String(raw['sync_buf'] ?? ''),
+        conversationConfirmed: !!raw['conversation_confirmed'],
+        linkedAt: String(raw['linked_at'] ?? ''),
+        baseUrl: String(raw['base_url'] ?? '') || ILINK_BASE_URL
+      }
+    } catch (err) {
+      console.error('[wechat] 凭据读取失败:', err)
+    }
+  }
+
+  private save(): void {
+    try {
+      const c = this.creds
+      writeFileSync(
+        this.credsPath,
+        JSON.stringify(
+          {
+            bot_token: c.botToken,
+            bot_id: c.botId,
+            user_id: c.userId,
+            push_target: c.pushTarget,
+            context_tokens: c.contextTokens,
+            context_token_ts: c.contextTokenTs,
+            sync_buf: c.syncBuf,
+            conversation_confirmed: c.conversationConfirmed,
+            linked_at: c.linkedAt,
+            base_url: c.baseUrl
+          },
+          null,
+          2
+        ),
+        'utf-8'
+      )
+    } catch (err) {
+      console.error('[wechat] 凭据写入失败:', err)
+    }
+  }
+
+  // ── 状态 ────────────────────────────────────────────────
+
+  get connected(): boolean {
+    return !!this.creds.botToken
+  }
+
+  get sessionAliveFlag(): boolean {
+    return this.sessionAlive
+  }
+
+  get isListening(): boolean {
+    return this.listening
+  }
+
+  get currentQrContent(): string | null {
+    return this.qrContent
+  }
+
+  getStatus(): WechatStatus {
+    return {
+      status: this.loginStatus,
+      statusText: LOGIN_STATUS_TEXT[this.loginStatus],
+      connected: this.connected,
+      sessionAlive: this.sessionAlive,
+      listening: this.listening,
+      botId: this.creds.botId,
+      pushTarget: this.creds.pushTarget,
+      linkedAt: this.creds.linkedAt,
+      qrContent: this.qrContent
+    }
+  }
+
+  private setStatus(status: WechatLoginStatus, extra = ''): void {
+    this.loginStatus = status
+    this.emit('status', { status, text: extra || LOGIN_STATUS_TEXT[status] })
+  }
+
+  setCommandHandler(handler: (text: string) => string | null): void {
+    this.commandHandler = handler
+  }
+
+  // ── HTTP 基础 ───────────────────────────────────────────
+
+  private anonHeaders(): Record<string, string> {
+    return {
+      'iLink-App-Id': 'bot',
+      'iLink-App-ClientVersion': String(ILINK_APP_CLIENT_VERSION)
+    }
+  }
+
+  private authHeaders(token: string): Record<string, string> {
+    // X-WECHAT-UIN: 随机 uin 的 base64（对齐旧版实现）
+    const uin = Buffer.from(String(Math.floor(Math.random() * 0xffffffff))).toString('base64')
+    return {
+      'Content-Type': 'application/json',
+      AuthorizationType: 'ilink_bot_token',
+      'X-WECHAT-UIN': uin,
+      'iLink-App-Id': 'bot',
+      'iLink-App-ClientVersion': String(ILINK_APP_CLIENT_VERSION),
+      Authorization: `Bearer ${token}`
+    }
+  }
+
+  private withBaseInfo<T extends object>(payload: T): T & { base_info: { channel_version: string } } {
+    return { ...payload, base_info: { channel_version: CHANNEL_VERSION } } as T & {
+      base_info: { channel_version: string }
+    }
+  }
+
+  private async getJson(url: string, headers: Record<string, string>, timeoutMs: number): Promise<Record<string, unknown>> {
+    const resp = await this.fetchImpl(url, {
+      method: 'GET',
+      headers,
+      signal: AbortSignal.timeout(timeoutMs)
+    })
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${url}`)
+    return (await resp.json()) as Record<string, unknown>
+  }
+
+  private async postJson(
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+    timeoutMs: number
+  ): Promise<Record<string, unknown>> {
+    const resp = await this.fetchImpl(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    })
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${url}`)
+    return (await resp.json()) as Record<string, unknown>
+  }
+
+  // ── 扫码登录 ────────────────────────────────────────────
+
+  private async fetchQrcode(baseUrl: string): Promise<{ qrId: string; content: string }> {
+    const data = await this.getJson(
+      `${baseUrl}/ilink/bot/get_bot_qrcode?bot_type=3`,
+      this.anonHeaders(),
+      QR_FETCH_TIMEOUT_MS
+    )
+    const qrId = String(data['qrcode'] ?? '').trim()
+    const content = String(data['qrcode_img_content'] ?? '').trim() || qrId
+    if (!qrId) throw new Error(`获取二维码失败: ${JSON.stringify(data)}`)
+    return { qrId, content }
+  }
+
+  private async pollQrStatus(baseUrl: string, qrId: string): Promise<Record<string, unknown>> {
+    return this.getJson(
+      `${baseUrl}/ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrId)}`,
+      this.anonHeaders(),
+      QR_FETCH_TIMEOUT_MS
+    )
+  }
+
+  /** 发起扫码登录（后台轮询，状态经 'status' 事件通知） */
+  startLogin(): boolean {
+    if (this.loginAbort) {
+      console.warn('[wechat] 已有登录流程在进行中')
+      return false
+    }
+    this.loginAbort = new AbortController()
+    void this.loginWorker(this.loginAbort.signal)
+    return true
+  }
+
+  cancelLogin(): void {
+    this.loginAbort?.abort()
+    this.loginAbort = null
+    if (this.loginStatus !== 'confirmed') this.setStatus('cancelled')
+  }
+
+  /**
+   * 应用启动时用已持久化的凭据自动恢复会话，无需重新扫码。
+   * 仅当存在有效 botToken 且当前未在监听时生效；若 token 已过期，
+   * 监听循环会收到 -14 并自动清空凭据、提示重新扫码。
+   */
+  resume(): boolean {
+    if (!this.connected || this.listening) return false
+    // iLink 的 context_token 约 24h 有效，且已持久化到磁盘。
+    // 只要磁盘上仍保存着该推送目标的令牌，就乐观认为会话活跃——重启后无需用户先发消息即可推送；
+    // 若令牌实际已过期，首次推送会返回 -2/-14，由 sendText 捕获并纠正状态。
+    if (this.creds.pushTarget && this.creds.contextTokens[this.creds.pushTarget]) {
+      this.sessionAlive = true
+    }
+    this.loginStatus = 'confirmed'
+    this.setStatus('confirmed', '已用本地凭据恢复连接')
+    this.startListening()
+    return true
+  }
+
+
+  private async loginWorker(signal: AbortSignal): Promise<void> {
+    const startedAt = Date.now()
+    let refreshCount = 0
+    let lastQrStatus = ''
+    try {
+      this.setStatus('fetching')
+      let { qrId, content } = await this.fetchQrcode(ILINK_BASE_URL)
+      this.qrContent = content
+      this.setStatus('waiting')
+      this.emit('qrcode', content)
+
+      while (!signal.aborted) {
+        if (Date.now() - startedAt > QR_LOGIN_TIMEOUT_MS) {
+          this.setStatus('timeout')
+          this.finishLogin(null)
+          return
+        }
+        const result = await this.pollQrStatus(ILINK_BASE_URL, qrId)
+        const status = String(result['status'] ?? 'wait').trim()
+
+        if (status === 'scaned' || status === 'scaned_but_redirect') {
+          if (lastQrStatus !== status) this.setStatus('scanned')
+        } else if (status === 'expired') {
+          refreshCount++
+          if (refreshCount > QR_EXPIRE_MAX) {
+            this.setStatus('timeout')
+            this.finishLogin(null)
+            return
+          }
+          const next = await this.fetchQrcode(ILINK_BASE_URL)
+          qrId = next.qrId
+          content = next.content
+          this.qrContent = content
+          this.setStatus('refreshed', `二维码已过期，已自动刷新 (${refreshCount}/${QR_EXPIRE_MAX})`)
+          this.emit('qrcode', content)
+        } else if (status === 'confirmed') {
+          const token = String(result['bot_token'] ?? '').trim()
+          const botId = String(result['ilink_bot_id'] ?? '').trim()
+          const userId = String(result['ilink_user_id'] ?? '').trim()
+          const confirmedBase = String(result['baseurl'] ?? '').trim() || ILINK_BASE_URL
+          if (!token || !botId) {
+            this.setStatus('failed')
+            this.finishLogin(new Error('登录已确认但返回凭据不完整'))
+            return
+          }
+          this.creds = {
+            ...emptyCredentials(),
+            botToken: token,
+            botId,
+            userId,
+            baseUrl: confirmedBase,
+            linkedAt: new Date().toLocaleString('zh-CN', { hour12: false })
+          }
+          this.sessionAlive = false
+          this.save()
+          this.setStatus('confirmed')
+          this.finishLogin(null)
+          this.startListening()
+          return
+        }
+        lastQrStatus = status
+        await sleep(QR_POLL_INTERVAL_MS, signal)
+      }
+      // aborted
+    } catch (err) {
+      if (signal.aborted) return
+      console.error('[wechat] 登录异常:', err)
+      this.setStatus('failed', `连接失败: ${String(err)}`)
+      this.finishLogin(err instanceof Error ? err : new Error(String(err)))
+    }
+  }
+
+  private finishLogin(_err: Error | null): void {
+    this.loginAbort = null
+  }
+
+  // ── 消息发送 ────────────────────────────────────────────
+
+  private async sendOnce(toUserId: string, text: string, contextToken: string | undefined): Promise<void> {
+    const msg: Record<string, unknown> = {
+      from_user_id: '',
+      to_user_id: toUserId,
+      client_id: `deskpet-${Math.random().toString(16).slice(2, 14)}`,
+      message_type: 2,
+      message_state: 2,
+      // 微信(iLink)文本项不把 \n 渲染为换行，用 \u000b 作为换行符（实测可正确分行）
+      item_list: [
+        {
+          type: 1,
+          text_item: { text: text.replace(/\r\n/g, '\u000b').replace(/\n/g, '\u000b') }
+        }
+      ]
+    }
+    if (contextToken) msg['context_token'] = contextToken
+
+    const data = await this.postJson(
+      `${this.creds.baseUrl}/ilink/bot/sendmessage`,
+      this.authHeaders(this.creds.botToken),
+      this.withBaseInfo({ msg }),
+      API_TIMEOUT_MS
+    )
+    const ret = Number(data['ret'] ?? 0)
+    const errcode = Number(data['errcode'] ?? 0)
+    if (ret !== 0 || errcode !== 0) {
+      throw new Error(JSON.stringify(data))
+    }
+  }
+
+  /** 发送文本（自动拆条；返回 {ok, message}） */
+  async sendText(text: string, toUserId?: string): Promise<{ ok: boolean; message: string }> {
+    if (!this.connected) return { ok: false, message: '微信未连接' }
+    const target = (toUserId ?? this.creds.pushTarget ?? '').trim()
+    if (!target) {
+      return {
+        ok: false,
+        message: '没有可用的推送目标：请先在微信里给机器人发一条消息（如「你好」）建立会话'
+      }
+    }
+    // iLink 协议：必须持有该用户的 context_token 才能推送（用户先发消息才会下发）。
+    // 该令牌已持久化到磁盘，24h 内重启后可直接复用，无需用户再次发消息。
+    const ctx = this.creds.contextTokens[target]
+    if (!ctx) {
+      return {
+        ok: false,
+        message: '尚无该用户的会话令牌：iLink 限制 bot 不能主动发起对话，请先在微信里给机器人发一条消息（如「你好」）'
+      }
+    }
+    const chunks = splitMessage(text)
+
+    for (let i = 0; i < chunks.length; i++) {
+      try {
+        await this.sendOnce(target, chunks[i], ctx)
+      } catch (err) {
+        // context_token 过期 / 登录会话失效 → 标记会话失效，等待用户重新发消息刷新
+        this.sessionAlive = false
+        const reason = this.classifySendError(err)
+        console.warn('[wechat] 推送失败:', reason)
+        return { ok: false, message: reason }
+      }
+      if (i < chunks.length - 1) await sleep(400)
+    }
+    this.sessionAlive = true
+    return { ok: true, message: '发送成功' }
+  }
+
+  /** 把推送异常归类成可读提示（区分登录会话过期与 context_token 过期/超限） */
+  private classifySendError(err: unknown): string {
+    const raw = err instanceof Error ? err.message : String(err)
+    try {
+      const data = JSON.parse(raw) as Record<string, unknown>
+      const ret = Number(data['ret'] ?? 0)
+      const errcode = Number(data['errcode'] ?? 0)
+      if (ret === -14 || errcode === -14) {
+        return '微信登录会话已过期，请到设置页重新扫码连接'
+      }
+      if (ret === -2 || errcode === -2) {
+        return '微信推送令牌已过期或达每日上限：请在微信里给机器人发一条消息（如「你好」）刷新会话后即可恢复推送'
+      }
+    } catch {
+      /* 非 JSON 错误（网络等），走通用文案 */
+    }
+    return `微信推送失败：${raw.slice(0, 200)}`
+  }
+
+  async sendTestMessage(): Promise<{ ok: boolean; message: string }> {
+    const now = new Date().toLocaleString('zh-CN', { hour12: false })
+    return this.sendText(`🐾 DeskPet 测试消息\n时间：${now}\n收到即说明推送链路正常`)
+  }
+
+  /** 任务结果推送（按设置过滤） */
+  async notifyTaskResult(taskName: string, success: boolean, detail = ''): Promise<void> {
+    const s = this.getSettings()
+    if (success && !s.notifyOnTaskComplete) return
+    if (!success && !s.notifyOnTaskFailed) return
+    const icon = success ? '✅' : '❌'
+    const lines = [`${icon} 任务${success ? '完成' : '失败'}：${taskName}`]
+    if (detail) lines.push(detail.slice(0, 500))
+    await this.sendText(lines.join('\n'))
+  }
+
+  // ── 长轮询接收 ──────────────────────────────────────────
+
+  startListening(): boolean {
+    if (!this.connected || this.listening) return false
+    this.listenStop = false
+    this.listening = true
+    this.lastPollAt = Date.now()
+    void this.listenLoop()
+
+    // 看门狗：长轮询卡死自动重启
+    if (!this.watchdog) {
+      this.watchdog = setInterval(() => {
+        if (!this.listening || this.listenStop) return
+        const staleMs = Date.now() - this.lastPollAt
+        if (staleMs > HEARTBEAT_STALE_THRESHOLD_MS) {
+          console.warn(`[wechat] 长轮询 ${Math.round(staleMs / 1000)}s 无响应，重启监听`)
+          this.listening = false
+          this.listenStop = true
+          setTimeout(() => {
+            if (this.connected && !this.listening) this.startListening()
+          }, 500)
+        }
+      }, HEARTBEAT_CHECK_INTERVAL_MS)
+      this.watchdog.unref?.()
+    }
+    return true
+  }
+
+  stopListening(): void {
+    this.listenStop = true
+    this.listening = false
+  }
+
+  private async listenLoop(): Promise<void> {
+    let failStreak = 0
+    this.reconnectAttempts = 0
+
+    while (!this.listenStop && this.connected) {
+      try {
+        const data = await this.postJson(
+          `${this.creds.baseUrl}/ilink/bot/getupdates`,
+          this.authHeaders(this.creds.botToken),
+          this.withBaseInfo({ get_updates_buf: this.creds.syncBuf }),
+          LONG_POLL_TIMEOUT_MS
+        )
+        failStreak = 0
+        this.lastPollAt = Date.now()
+
+        const ret = Number(data['ret'] ?? 0)
+        const errcode = Number(data['errcode'] ?? 0)
+
+        // 会话过期 → 自动重连
+        if (ret === -14 || errcode === -14) {
+          const ok = await this.tryReconnect()
+          if (ok) continue
+          this.creds.botToken = ''
+          this.sessionAlive = false
+          this.save()
+          this.listening = false
+          this.emit('disconnected', '微信会话已过期，自动重连失败，请重新扫码连接')
+          return
+        }
+
+        if (ret !== 0 || errcode !== 0) {
+          await sleep(3000)
+          continue
+        }
+
+        let dirty = false
+        const newBuf = String(data['get_updates_buf'] ?? '')
+        if (newBuf && newBuf !== this.creds.syncBuf) {
+          this.creds.syncBuf = newBuf
+          dirty = true
+        }
+        const msgs = (data['msgs'] as Array<Record<string, unknown>>) ?? []
+        for (const msg of msgs) {
+          if (this.handleIncoming(msg)) dirty = true
+        }
+        if (dirty) this.save()
+      } catch (err) {
+        // 长轮询超时属正常，静默重试
+        const name = err instanceof Error ? err.name : String(err)
+        if (!name.includes('Timeout') && !name.includes('AbortError')) {
+          failStreak++
+          if (failStreak === 5) {
+            console.warn('[wechat] 长轮询连续失败 5 次，可能网络不稳定')
+          }
+          const backoff = Math.min(3000 * failStreak, 30_000)
+          await sleep(backoff)
+        }
+      }
+    }
+    this.listening = false
+  }
+
+  private async tryReconnect(): Promise<boolean> {
+    if (this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) return false
+    this.reconnectAttempts++
+    console.warn(`[wechat] 会话过期，尝试自动重连 (第${this.reconnectAttempts}次)`)
+    await sleep(RECONNECT_DELAY_MS)
+    // iLink 协议：bot_token 失效后无法本地续期，只能提示重新扫码
+    return false
+  }
+
+  /** 处理一条收到的消息；返回是否有状态需要落盘 */
+  private handleIncoming(msg: Record<string, unknown>): boolean {
+    const fromUid = String(msg['from_user_id'] ?? '').trim()
+    if (!fromUid || fromUid === this.creds.botId) return false
+
+    let dirty = false
+    const ctxToken = String(msg['context_token'] ?? '').trim()
+    if (ctxToken && this.creds.contextTokens[fromUid] !== ctxToken) {
+      this.creds.contextTokens[fromUid] = ctxToken
+      this.creds.contextTokenTs[fromUid] = Date.now()
+      dirty = true
+    }
+    // 用户主动发消息 = 推送会话恢复活跃
+    this.sessionAlive = true
+    if (this.creds.pushTarget !== fromUid) {
+      this.creds.pushTarget = fromUid
+      dirty = true
+    }
+    // 首次会话确认
+    if (!this.creds.conversationConfirmed) {
+      this.creds.conversationConfirmed = true
+      dirty = true
+      void this.sendText(
+        '✅ 微信会话已建立\n之后任务执行结果和测试消息都会推送到这里。\n发「帮助」查看可用指令。',
+        fromUid
+      )
+    }
+
+    const text = extractText(msg)
+    if (!text) return dirty
+    this.emit('message', { fromUid, text })
+
+    // 指令处理（未命中由 router 返回提示；allowRemoteCommand=false 时忽略）
+    if (this.commandHandler && this.getSettings().allowRemoteCommand) {
+      let reply: string | null
+      try {
+        reply = this.commandHandler(text)
+      } catch (err) {
+        reply = `❌ 指令执行出错: ${String(err)}`
+      }
+      if (reply) void this.sendText(reply, fromUid)
+    }
+    return dirty
+  }
+
+  // ── 断开 ────────────────────────────────────────────────
+
+  disconnect(): void {
+    this.cancelLogin()
+    this.stopListening()
+    if (this.watchdog) {
+      clearInterval(this.watchdog)
+      this.watchdog = null
+    }
+    this.creds = emptyCredentials()
+    this.sessionAlive = false
+    this.loginStatus = 'idle'
+    this.qrContent = null
+    try {
+      if (existsSync(this.credsPath)) writeFileSync(this.credsPath, '', 'utf-8')
+    } catch {
+      /* ignore */
+    }
+    this.emit('status', { status: 'idle', text: LOGIN_STATUS_TEXT.idle })
+  }
+
+  /** 应用退出时调用 */
+  shutdown(): void {
+    this.stopListening()
+    if (this.watchdog) {
+      clearInterval(this.watchdog)
+      this.watchdog = null
+    }
+    this.loginAbort?.abort()
+  }
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms)
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(t)
+        resolve()
+      },
+      { once: true }
+    )
+  })
+}