dsh-qqchat 0.2.0

package/src/gateway/api.ts

@@ -0,0 +1,260 @@
+import type { QQChatDatabase } from '../storage/db.js'
+import type {
+  AccountRow,
+  QQAccessTokenPayload,
+  QQChatConfig,
+  QQGatewayPayload,
+  QQSendOptions,
+  ReplyFormat,
+} from '../types.js'
+
+const API_BASE = 'https://api.sgroup.qq.com'
+const SANDBOX_API_BASE = 'https://sandbox.api.sgroup.qq.com'
+const TOKEN_URL = 'https://bots.qq.com/app/getAppAccessToken'
+
+function looksLikeMarkdown(text: string): boolean {
+  return /(^|\n)\s{0,3}(#{1,6}\s|[-*+]\s|\d+\.\s|>\s)|\*\*|__|`|\[[^\]]+\]\([^\)]+\)/m.test(text)
+}
+
+interface CachedToken {
+  token: string
+  expiresAt: number
+}
+
+interface QQSendBody {
+  msg_type: number
+  msg_seq: number
+  msg_id?: string
+  content?: string
+  markdown?: { content: string }
+}
+
+interface QQStreamBody {
+  input_mode: 'replace'
+  input_state: 1 | 10
+  index: number
+  content_type: 'text' | 'markdown'
+  content_raw: string
+  msg_seq: number
+  event_id?: string
+  msg_id?: string
+  stream_msg_id?: string
+}
+
+export interface QQPrivateTextStream {
+  push(delta: string): void
+  finish(text: string): Promise<void>
+  hasSent(): boolean
+}
+
+export class QQApiClient {
+  private readonly tokens = new Map<number, CachedToken>()
+  private readonly sequences = new Map<string, number>()
+  private streamSequence = (Date.now() ^ Math.floor(Math.random() * 65_536)) & 0xffff
+
+  constructor(
+    private readonly db: QQChatDatabase,
+    readonly config: QQChatConfig,
+  ) {}
+
+  clearToken(accountId: number): void { this.tokens.delete(Number(accountId)) }
+
+  async token(account: AccountRow): Promise<string> {
+    const id = Number(account.id)
+    const cached = this.tokens.get(id)
+    if (cached && cached.expiresAt > Date.now() + 60_000) return cached.token
+    const response = await fetch(TOKEN_URL, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ appId: account.app_id, clientSecret: account.app_secret }),
+      signal: AbortSignal.timeout(15_000),
+    })
+    const data = await safeJson<QQAccessTokenPayload>(response)
+    if (!response.ok || !data?.access_token) throw new Error(`QQ access_token 获取失败: HTTP ${response.status}`)
+    const ttl = Number(data.expires_in || 7200)
+    this.tokens.set(id, { token: data.access_token, expiresAt: Date.now() + Math.max(60, ttl) * 1000 })
+    return data.access_token
+  }
+
+  async gatewayUrl(account: AccountRow): Promise<string> {
+    const token = await this.token(account)
+    const base = account.sandbox ? SANDBOX_API_BASE : API_BASE
+    const response = await fetch(`${base}/gateway`, {
+      headers: { Authorization: `QQBot ${token}` }, signal: AbortSignal.timeout(15_000),
+    })
+    const data = await safeJson<QQGatewayPayload>(response)
+    if (!response.ok || !data?.url) throw new Error(`QQ gateway 获取失败: HTTP ${response.status}`)
+    return data.url
+  }
+
+  private nextSeq(messageId: string | null | undefined): number {
+    const key = messageId || `active:${Date.now()}:${Math.random()}`
+    const next = (this.sequences.get(key) || 0) + 1
+    this.sequences.set(key, next)
+    return next
+  }
+
+  /**
+   * QQ stream_messages requires a fresh msg_seq for each stream session.
+   * It is intentionally not scoped by the inbound message id: using 1 for
+   * every reply causes QQ to reject later streams as duplicated messages.
+   */
+  private nextStreamSeq(): number {
+    this.streamSequence = (this.streamSequence + 1) & 0xffff
+    return this.streamSequence
+  }
+
+  private async request<T = Record<string, unknown>>(
+    account: AccountRow,
+    method: string,
+    path: string,
+    body: unknown,
+    retry = true,
+  ): Promise<T> {
+    const token = await this.token(account)
+    const base = account.sandbox ? SANDBOX_API_BASE : API_BASE
+    const response = await fetch(`${base}${path}`, {
+      method,
+      headers: { Authorization: `QQBot ${token}`, 'content-type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(20_000),
+    })
+    const data = await safeJson<Record<string, unknown>>(response)
+    if (response.status === 401 && retry) {
+      this.clearToken(account.id)
+      return this.request<T>(account, method, path, body, false)
+    }
+    if (!response.ok) {
+      const code = data?.code ? ` code=${String(data.code)}` : ''
+      const message = data?.message ? ` ${String(data.message)}` : ''
+      throw new Error(`QQ API HTTP ${response.status}${code}${message}`)
+    }
+    return (data || {}) as T
+  }
+
+  async sendText(
+    account: AccountRow,
+    targetId: string,
+    text: string,
+    { group = false, messageId = null, format = this.config.replyFormat }: QQSendOptions = {},
+  ): Promise<Record<string, unknown>> {
+    const path = group ? `/v2/groups/${encodeURIComponent(targetId)}/messages` : `/v2/users/${encodeURIComponent(targetId)}/messages`
+    const seq = this.nextSeq(messageId)
+    const useMarkdown = format === 'markdown' || (format === 'smart' && looksLikeMarkdown(text))
+    const makeBody = (markdown: boolean): QQSendBody => ({
+      msg_type: markdown ? 2 : 0,
+      ...(markdown ? { markdown: { content: text } } : { content: text }),
+      msg_seq: seq,
+      ...(messageId ? { msg_id: messageId } : {}),
+    })
+    try {
+      return await this.request(account, 'POST', path, makeBody(useMarkdown))
+    } catch (error) {
+      if (useMarkdown && /50056|markdown|md perm/i.test(String(error))) {
+        return this.request(account, 'POST', path, makeBody(false))
+      }
+      throw error
+    }
+  }
+
+  async sendReplyWithActiveFallback(
+    account: AccountRow,
+    targetId: string,
+    text: string,
+    options: QQSendOptions,
+  ): Promise<Record<string, unknown>> {
+    try {
+      return await this.sendText(account, targetId, text, options)
+    } catch (error) {
+      if (!options.messageId) throw error
+      return this.sendText(account, targetId, text, { ...options, messageId: null })
+    }
+  }
+
+  createPrivateTextStream(
+    account: AccountRow,
+    targetId: string,
+    { messageId = null, format = this.config.replyFormat }: QQSendOptions = {},
+  ): QQPrivateTextStream {
+    const path = `/v2/users/${encodeURIComponent(targetId)}/stream_messages`
+    const msgSeq = this.nextStreamSeq()
+    const contentType = format === 'markdown' ? 'markdown' : 'text'
+    let fullText = ''
+    let streamMessageId: string | undefined
+    let index = 0
+    let sent = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let chain = Promise.resolve()
+    let finished = false
+    let lastSentText = ''
+
+    const enqueue = (inputState: 1 | 10, content: string): Promise<void> => {
+      chain = chain.then(async () => {
+        // Build the request only when the queued task runs. The first
+        // response supplies stream_msg_id for all following frames.
+        const body: QQStreamBody = {
+          input_mode: 'replace', input_state: inputState, index: index++, content_type: contentType,
+          content_raw: content, msg_seq: msgSeq,
+          ...(messageId ? { msg_id: messageId, event_id: messageId } : {}),
+          ...(streamMessageId ? { stream_msg_id: streamMessageId } : {}),
+        }
+        let attempt = 0
+        while (true) {
+          try {
+            const result = await this.request<{ stream_msg_id?: unknown; id?: unknown }>(account, 'POST', path, body)
+            sent = true
+            if (!streamMessageId) {
+              const id = typeof result.stream_msg_id === 'string' ? result.stream_msg_id : result.id
+              if (typeof id === 'string' && id) streamMessageId = id
+            }
+            lastSentText = content
+            return
+          } catch (error) {
+            const message = String(error)
+            const rateLimited = /HTTP 429|50002|rate limit/i.test(message)
+            if (!rateLimited || attempt >= 3) throw error
+            const delay = 1000 * (2 ** attempt++)
+            await new Promise(resolve => setTimeout(resolve, delay))
+          }
+        }
+      })
+      return chain
+    }
+
+    const flush = (inputState: 1 | 10 = 1): Promise<void> => {
+      timer = undefined
+      if (!fullText && inputState !== 10) return chain
+      if (inputState !== 10 && fullText === lastSentText) return chain
+      return enqueue(inputState, fullText)
+    }
+
+    return {
+      push: delta => {
+        if (!delta || finished) return
+        fullText += delta
+        if (!timer) {
+          timer = setTimeout(() => { void flush().catch(() => {}) }, 500)
+          timer.unref?.()
+        }
+      },
+      finish: async text => {
+        finished = true
+        if (timer) clearTimeout(timer)
+        timer = undefined
+        fullText = text
+        await flush(1)
+        await chain
+        await flush(10)
+        await chain
+      },
+      hasSent: () => sent,
+    }
+  }
+}
+
+async function safeJson<T>(response: Response): Promise<T | undefined> {
+  try { return await response.json() as T } catch { return undefined }
+}
+
+export function isReplyFormat(value: string): value is ReplyFormat {
+  return value === 'smart' || value === 'markdown' || value === 'compat'
+}

package/src/gateway/auth.ts

@@ -0,0 +1,99 @@
+import { randomBytes } from 'node:crypto'
+import QRCode from 'qrcode'
+import { decryptQQSecret } from './crypto.js'
+import type { QQChatDatabase } from '../storage/db.js'
+import type { AccountRow, QQBindCreatePayload, QQBindPollPayload, QQChatConfig } from '../types.js'
+
+const CREATE_URL = 'https://q.qq.com/lite/create_bind_task'
+const POLL_URL = 'https://q.qq.com/lite/poll_bind_result'
+const FRONTEND = 'https://q.qq.com/qqbot/openclaw/connect.html'
+const TASK_TTL_MS = 600_000
+
+export interface QQBindStartResult {
+  taskId: string
+  scanUrl: string
+  qrDataUrl: string
+  expiresInMs: number
+}
+
+export type QQBindPollResult =
+  | { status: 'waiting' }
+  | { status: 'expired' }
+  | { status: 'fail'; reason: string }
+  | { status: 'success'; account: PublicAccount }
+
+export interface PublicAccount {
+  id: number
+  appId: string
+  botUserId: string | null
+  enabled: boolean
+  sandbox: boolean
+  gatewayStatus: string
+  gatewayLastError: string | null
+}
+
+export class QQBindService {
+  constructor(
+    private readonly db: QQChatDatabase,
+    private readonly config: QQChatConfig,
+  ) {}
+
+  async start(): Promise<QQBindStartResult> {
+    const aesKey = randomBytes(32).toString('base64')
+    const response = await fetch(CREATE_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key: aesKey }),
+      signal: AbortSignal.timeout(15_000),
+    })
+    if (!response.ok) throw new Error(`QQ 创建连接任务失败: HTTP ${response.status}`)
+    const payload = await response.json() as QQBindCreatePayload
+    if (payload.retcode !== 0) throw new Error(`QQ 创建连接任务失败: ${payload.msg || 'unknown'}`)
+    const taskId = payload.data?.task_id
+    if (!taskId) throw new Error('QQ 未返回 task_id')
+    this.db.saveAuthTask(String(taskId), aesKey, TASK_TTL_MS)
+    const scanUrl = `${FRONTEND}?task_id=${encodeURIComponent(taskId)}&_wv=2&source=${encodeURIComponent(this.config.source)}`
+    const qrDataUrl = await QRCode.toDataURL(scanUrl, { width: 224, margin: 1, errorCorrectionLevel: 'M' })
+    return { taskId: String(taskId), scanUrl, qrDataUrl, expiresInMs: TASK_TTL_MS }
+  }
+
+  async poll(taskId: string): Promise<QQBindPollResult> {
+    const task = this.db.getAuthTask(taskId)
+    if (!task) return { status: 'expired' }
+    const response = await fetch(POLL_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ task_id: taskId }),
+      signal: AbortSignal.timeout(10_000),
+    })
+    if (!response.ok) throw new Error(`QQ 轮询授权失败: HTTP ${response.status}`)
+    const payload = await response.json() as QQBindPollPayload
+    if (payload.retcode !== 0) return { status: 'fail', reason: payload.msg || 'unknown' }
+    const data = payload.data || {}
+    if (data.status === 3) {
+      this.db.deleteAuthTask(taskId)
+      return { status: 'expired' }
+    }
+    if (data.status !== 2) return { status: 'waiting' }
+    const appId = String(data.bot_appid || '')
+    const encrypted = String(data.bot_encrypt_secret || '')
+    if (!appId || !encrypted) return { status: 'fail', reason: 'QQ 返回缺少 AppID 或 Secret' }
+    let secret: string
+    try {
+      secret = decryptQQSecret(encrypted, task.aes_key)
+    } catch {
+      return { status: 'fail', reason: 'QQ Secret 解密失败' }
+    }
+    const account = this.db.upsertAccount(appId, secret, this.config.sandbox)
+    this.db.deleteAuthTask(taskId)
+    return { status: 'success', account: publicAccount(account) }
+  }
+}
+
+function publicAccount(account: AccountRow): PublicAccount {
+  return {
+    id: Number(account.id), appId: account.app_id, botUserId: account.bot_user_id || null,
+    enabled: account.enabled === 1, sandbox: account.sandbox === 1,
+    gatewayStatus: account.gateway_status, gatewayLastError: account.gateway_last_error || null,
+  }
+}

package/src/gateway/crypto.ts

@@ -0,0 +1,16 @@
+import { createDecipheriv } from 'node:crypto'
+
+/** QQ bind_task returns base64(iv[12] + ciphertext + gcmTag[16]). */
+export function decryptQQSecret(encryptedBase64: string, keyBase64: string): string {
+  const key = Buffer.from(keyBase64, 'base64')
+  const raw = Buffer.from(encryptedBase64, 'base64')
+  if (key.length !== 32) throw new Error('QQ bind AES key must be 32 bytes')
+  if (raw.length < 28) throw new Error('QQ bind ciphertext is too short')
+  const iv = raw.subarray(0, 12)
+  const body = raw.subarray(12)
+  const tag = body.subarray(body.length - 16)
+  const ciphertext = body.subarray(0, body.length - 16)
+  const decipher = createDecipheriv('aes-256-gcm', key, iv)
+  decipher.setAuthTag(tag)
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8')
+}

package/src/gateway/gateway.ts

@@ -0,0 +1,207 @@
+import { normalizeQQDispatch } from './normalize.js'
+import type { QQApiClient } from './api.js'
+import type { QQChatDatabase } from '../storage/db.js'
+import type { AccountRow, LoggerLike, QQDispatchData, QQGatewayFrame, QQNormalizedMessage } from '../types.js'
+
+const OP = {
+  DISPATCH: 0,
+  HEARTBEAT: 1,
+  IDENTIFY: 2,
+  RESUME: 6,
+  RECONNECT: 7,
+  INVALID_SESSION: 9,
+  HELLO: 10,
+  HEARTBEAT_ACK: 11,
+} as const
+
+const INTENTS = 1 << 25
+const RECONNECT_DELAYS = [1000, 2000, 5000, 10_000, 30_000, 60_000] as const
+
+type QQMessageHandler = (message: QQNormalizedMessage) => Promise<void> | void
+
+export class QQGateway {
+  private stopped = false
+  private ws?: WebSocket
+  private sessionId?: string
+  private lastSeq: number | null = null
+  private heartbeatTimer?: ReturnType<typeof setInterval>
+  private ackTimer?: ReturnType<typeof setTimeout>
+  private lastAckAt = 0
+  private loopPromise?: Promise<void>
+  private readonly dispatchChains = new Map<string, Promise<void>>()
+
+  constructor(
+    readonly account: AccountRow,
+    private readonly db: QQChatDatabase,
+    private readonly api: QQApiClient,
+    private readonly onMessage: QQMessageHandler,
+    private readonly logger: LoggerLike = console,
+  ) {}
+
+  start(): void {
+    if (this.loopPromise) return
+    this.stopped = false
+    this.loopPromise = this.loop().finally(() => { this.loopPromise = undefined })
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true
+    this.clearHeartbeat()
+    try { this.ws?.close() } catch {}
+    try { await this.loopPromise } catch {}
+    this.db.setAccountGateway(this.account.id, 'offline', null)
+  }
+
+  private async loop(): Promise<void> {
+    let attempt = 0
+    while (!this.stopped) {
+      try {
+        this.db.setAccountGateway(this.account.id, 'connecting', null)
+        await this.connectOnce()
+        attempt = 0
+      } catch (error) {
+        if (this.stopped) break
+        const message = error instanceof Error ? error.message : String(error)
+        this.db.setAccountGateway(this.account.id, 'error', message.slice(0, 500))
+        this.logger.warn?.(`[dsh-qqchat] QQ gateway: ${message}`)
+        const delay = RECONNECT_DELAYS[Math.min(attempt++, RECONNECT_DELAYS.length - 1)] ?? RECONNECT_DELAYS.at(-1) ?? 60_000
+        await sleep(delay)
+      }
+    }
+  }
+
+  private async connectOnce(): Promise<void> {
+    const [url, token] = await Promise.all([this.api.gatewayUrl(this.account), this.api.token(this.account)])
+    await new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(url)
+      this.ws = ws
+      let settled = false
+      const finish = (error?: Error): void => {
+        if (settled) return
+        settled = true
+        this.clearHeartbeat()
+        this.ws = undefined
+        if (error) reject(error)
+        else resolve()
+      }
+      ws.addEventListener('error', () => finish(new Error('QQ WebSocket 连接错误')))
+      ws.addEventListener('close', event => {
+        if (this.stopped) finish()
+        else finish(new Error(`QQ WebSocket 已断开 (${event.code})`))
+      })
+      ws.addEventListener('message', event => {
+        this.handleFrame(ws, token, event.data).catch(error => {
+          try { ws.close() } catch {}
+          finish(error instanceof Error ? error : new Error(String(error)))
+        })
+      })
+    })
+  }
+
+  private async handleFrame(ws: WebSocket, token: string, raw: unknown): Promise<void> {
+    const text = await asText(raw)
+    const frame = JSON.parse(text) as QQGatewayFrame
+    if (typeof frame.s === 'number') this.lastSeq = frame.s
+    switch (frame.op) {
+      case OP.HELLO: {
+        const interval = Number(frame.d?.heartbeat_interval || 45_000)
+        this.installHeartbeat(ws, interval)
+        if (this.sessionId) {
+          this.send(ws, OP.RESUME, { token: `QQBot ${token}`, session_id: this.sessionId, seq: this.lastSeq })
+        } else {
+          this.send(ws, OP.IDENTIFY, {
+            token: `QQBot ${token}`,
+            intents: INTENTS,
+            shard: [0, 1],
+            properties: { $os: process.platform, $browser: 'dsh-qqchat', $device: 'dsh-qqchat' },
+          })
+        }
+        break
+      }
+      case OP.HEARTBEAT_ACK:
+        this.lastAckAt = Date.now()
+        break
+      case OP.RECONNECT:
+        ws.close(4000, 'server reconnect')
+        break
+      case OP.INVALID_SESSION:
+        this.sessionId = undefined
+        this.lastSeq = null
+        ws.close(4001, 'invalid session')
+        break
+      case OP.DISPATCH:
+        await this.handleDispatch(frame.t || '', frame.d || {})
+        break
+    }
+  }
+
+  private async handleDispatch(type: string, data: Record<string, unknown>): Promise<void> {
+    if (type === 'READY') {
+      const sessionId = data.session_id
+      this.sessionId = typeof sessionId === 'string' && sessionId ? sessionId : this.sessionId
+      const user = isRecord(data.user) ? data.user : undefined
+      const botUserId = String(user?.id || user?.openid || '') || undefined
+      this.db.setAccountGateway(this.account.id, 'online', null, botUserId)
+      return
+    }
+    if (type === 'RESUMED') {
+      this.db.setAccountGateway(this.account.id, 'online', null)
+      return
+    }
+    const message = normalizeQQDispatch(type, data as QQDispatchData, Number(this.account.id))
+    if (message) await this.enqueueMessage(message)
+  }
+
+  private enqueueMessage(message: QQNormalizedMessage): Promise<void> {
+    const key = `${this.account.id}:${message.chatType}:${message.chatId}`
+    const previous = this.dispatchChains.get(key) || Promise.resolve()
+    const current = previous.catch(() => undefined).then(() => this.onMessage(message))
+    this.dispatchChains.set(key, current)
+    return current.finally(() => {
+      if (this.dispatchChains.get(key) === current) this.dispatchChains.delete(key)
+    })
+  }
+
+  private installHeartbeat(ws: WebSocket, interval: number): void {
+    this.clearHeartbeat()
+    this.lastAckAt = Date.now()
+    const tick = (): void => {
+      if (ws.readyState !== WebSocket.OPEN) return
+      if (Date.now() - this.lastAckAt > interval * 2.5) {
+        ws.close(4002, 'heartbeat timeout')
+        return
+      }
+      this.send(ws, OP.HEARTBEAT, this.lastSeq)
+    }
+    this.heartbeatTimer = setInterval(tick, interval)
+    const firstTick = setTimeout(tick, Math.min(1000, interval))
+    firstTick.unref?.()
+  }
+
+  private clearHeartbeat(): void {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+    if (this.ackTimer) clearTimeout(this.ackTimer)
+    this.heartbeatTimer = undefined
+    this.ackTimer = undefined
+  }
+
+  private send(ws: WebSocket, op: number, data: unknown): void {
+    if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ op, d: data }))
+  }
+}
+
+async function asText(data: unknown): Promise<string> {
+  if (typeof data === 'string') return data
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString('utf8')
+  if (ArrayBuffer.isView(data)) return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('utf8')
+  if (data instanceof Blob) return data.text()
+  return String(data)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}