dsh-qqchat 0.2.0

package/lib/gateway/api.js

@@ -0,0 +1,202 @@
+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) {
+    return /(^|\n)\s{0,3}(#{1,6}\s|[-*+]\s|\d+\.\s|>\s)|\*\*|__|`|\[[^\]]+\]\([^\)]+\)/m.test(text);
+}
+export class QQApiClient {
+    db;
+    config;
+    tokens = new Map();
+    sequences = new Map();
+    streamSequence = (Date.now() ^ Math.floor(Math.random() * 65_536)) & 0xffff;
+    constructor(db, config) {
+        this.db = db;
+        this.config = config;
+    }
+    clearToken(accountId) { this.tokens.delete(Number(accountId)); }
+    async token(account) {
+        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(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) {
+        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(response);
+        if (!response.ok || !data?.url)
+            throw new Error(`QQ gateway 获取失败: HTTP ${response.status}`);
+        return data.url;
+    }
+    nextSeq(messageId) {
+        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.
+     */
+    nextStreamSeq() {
+        this.streamSequence = (this.streamSequence + 1) & 0xffff;
+        return this.streamSequence;
+    }
+    async request(account, method, path, body, retry = true) {
+        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(response);
+        if (response.status === 401 && retry) {
+            this.clearToken(account.id);
+            return this.request(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 || {});
+    }
+    async sendText(account, targetId, text, { group = false, messageId = null, format = this.config.replyFormat } = {}) {
+        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) => ({
+            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, targetId, text, options) {
+        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, targetId, { messageId = null, format = this.config.replyFormat } = {}) {
+        const path = `/v2/users/${encodeURIComponent(targetId)}/stream_messages`;
+        const msgSeq = this.nextStreamSeq();
+        const contentType = format === 'markdown' ? 'markdown' : 'text';
+        let fullText = '';
+        let streamMessageId;
+        let index = 0;
+        let sent = false;
+        let timer;
+        let chain = Promise.resolve();
+        let finished = false;
+        let lastSentText = '';
+        const enqueue = (inputState, content) => {
+            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 = {
+                    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(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) => {
+            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(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isReplyFormat(value) {
+    return value === 'smart' || value === 'markdown' || value === 'compat';
+}

package/lib/gateway/auth.d.ts

@@ -0,0 +1,35 @@
+import type { QQChatDatabase } from '../storage/db.js';
+import type { QQChatConfig } from '../types.js';
+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 declare class QQBindService {
+    private readonly db;
+    private readonly config;
+    constructor(db: QQChatDatabase, config: QQChatConfig);
+    start(): Promise<QQBindStartResult>;
+    poll(taskId: string): Promise<QQBindPollResult>;
+}

package/lib/gateway/auth.js

@@ -0,0 +1,80 @@
+import { randomBytes } from 'node:crypto';
+import QRCode from 'qrcode';
+import { decryptQQSecret } from './crypto.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 class QQBindService {
+    db;
+    config;
+    constructor(db, config) {
+        this.db = db;
+        this.config = config;
+    }
+    async start() {
+        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();
+        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) {
+        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();
+        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;
+        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) {
+    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/lib/gateway/crypto.d.ts

@@ -0,0 +1,2 @@
+/** QQ bind_task returns base64(iv[12] + ciphertext + gcmTag[16]). */
+export declare function decryptQQSecret(encryptedBase64: string, keyBase64: string): string;

package/lib/gateway/crypto.js

@@ -0,0 +1,17 @@
+import { createDecipheriv } from 'node:crypto';
+/** QQ bind_task returns base64(iv[12] + ciphertext + gcmTag[16]). */
+export function decryptQQSecret(encryptedBase64, keyBase64) {
+    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/lib/gateway/gateway.d.ts

@@ -0,0 +1,32 @@
+import type { QQApiClient } from './api.js';
+import type { QQChatDatabase } from '../storage/db.js';
+import type { AccountRow, LoggerLike, QQNormalizedMessage } from '../types.js';
+type QQMessageHandler = (message: QQNormalizedMessage) => Promise<void> | void;
+export declare class QQGateway {
+    readonly account: AccountRow;
+    private readonly db;
+    private readonly api;
+    private readonly onMessage;
+    private readonly logger;
+    private stopped;
+    private ws?;
+    private sessionId?;
+    private lastSeq;
+    private heartbeatTimer?;
+    private ackTimer?;
+    private lastAckAt;
+    private loopPromise?;
+    private readonly dispatchChains;
+    constructor(account: AccountRow, db: QQChatDatabase, api: QQApiClient, onMessage: QQMessageHandler, logger?: LoggerLike);
+    start(): void;
+    stop(): Promise<void>;
+    private loop;
+    private connectOnce;
+    private handleFrame;
+    private handleDispatch;
+    private enqueueMessage;
+    private installHeartbeat;
+    private clearHeartbeat;
+    private send;
+}
+export {};

package/lib/gateway/gateway.js

@@ -0,0 +1,219 @@
+import { normalizeQQDispatch } from './normalize.js';
+const OP = {
+    DISPATCH: 0,
+    HEARTBEAT: 1,
+    IDENTIFY: 2,
+    RESUME: 6,
+    RECONNECT: 7,
+    INVALID_SESSION: 9,
+    HELLO: 10,
+    HEARTBEAT_ACK: 11,
+};
+const INTENTS = 1 << 25;
+const RECONNECT_DELAYS = [1000, 2000, 5000, 10_000, 30_000, 60_000];
+export class QQGateway {
+    account;
+    db;
+    api;
+    onMessage;
+    logger;
+    stopped = false;
+    ws;
+    sessionId;
+    lastSeq = null;
+    heartbeatTimer;
+    ackTimer;
+    lastAckAt = 0;
+    loopPromise;
+    dispatchChains = new Map();
+    constructor(account, db, api, onMessage, logger = console) {
+        this.account = account;
+        this.db = db;
+        this.api = api;
+        this.onMessage = onMessage;
+        this.logger = logger;
+    }
+    start() {
+        if (this.loopPromise)
+            return;
+        this.stopped = false;
+        this.loopPromise = this.loop().finally(() => { this.loopPromise = undefined; });
+    }
+    async stop() {
+        this.stopped = true;
+        this.clearHeartbeat();
+        try {
+            this.ws?.close();
+        }
+        catch { }
+        try {
+            await this.loopPromise;
+        }
+        catch { }
+        this.db.setAccountGateway(this.account.id, 'offline', null);
+    }
+    async loop() {
+        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);
+            }
+        }
+    }
+    async connectOnce() {
+        const [url, token] = await Promise.all([this.api.gatewayUrl(this.account), this.api.token(this.account)]);
+        await new Promise((resolve, reject) => {
+            const ws = new WebSocket(url);
+            this.ws = ws;
+            let settled = false;
+            const finish = (error) => {
+                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)));
+                });
+            });
+        });
+    }
+    async handleFrame(ws, token, raw) {
+        const text = await asText(raw);
+        const frame = JSON.parse(text);
+        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;
+        }
+    }
+    async handleDispatch(type, data) {
+        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, Number(this.account.id));
+        if (message)
+            await this.enqueueMessage(message);
+    }
+    enqueueMessage(message) {
+        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);
+        });
+    }
+    installHeartbeat(ws, interval) {
+        this.clearHeartbeat();
+        this.lastAckAt = Date.now();
+        const tick = () => {
+            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?.();
+    }
+    clearHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        if (this.ackTimer)
+            clearTimeout(this.ackTimer);
+        this.heartbeatTimer = undefined;
+        this.ackTimer = undefined;
+    }
+    send(ws, op, data) {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(JSON.stringify({ op, d: data }));
+    }
+}
+async function asText(data) {
+    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) {
+    return typeof value === 'object' && value !== null;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/lib/gateway/normalize.d.ts

@@ -0,0 +1,6 @@
+import type { QQDispatchData, QQNormalizedMessage } from '../types.js';
+/** Replace QQ's stable mention tokens with the best known display name. */
+export declare function renderQQMentionNames(text: string, data: QQDispatchData, lookup?: (platformUserId: string) => string | undefined): string;
+export declare function messageMentionsBot(data: QQDispatchData, eventType: string): boolean;
+export declare function botMentionId(data: QQDispatchData, eventType: string): string;
+export declare function normalizeQQDispatch(eventType: string, data: QQDispatchData | undefined, accountId: number): QQNormalizedMessage | undefined;