@downcity/plugins 1.0.4

package/bin/chat/channels/qq/QQ.js

@@ -0,0 +1,287 @@
+/**
+ * QQ 渠道门面。
+ *
+ * 关键点（中文）
+ * - `QQBot` 只保留渠道层编排职责：入站授权、命令处理、消息入队、回复调度。
+ * - Gateway 连接、自愈重连、消息回发已经下沉到 `QQGatewayClient`。
+ * - 文本清洗、作者识别、标题解析、附件宽松提取已经下沉到 `QQInbound`。
+ * - READY 身份解析、命令映射、入站增强组装已经下沉到 `QQSupport`。
+ */
+import { BaseChatChannel } from "../../../chat/channels/BaseChatChannel.js";
+import { parseChatMessageMarkup } from "@downcity/agent/internal/executor/messages/ChatMessageMarkup.js";
+import { QqInboundDedupeStore } from "./QQInboundDedupe.js";
+import { getQqEventCaptureConfig } from "./QQEventCapture.js";
+import { QQGatewayClient } from "./QQGatewayClient.js";
+import { extractQqReadyIdentity, resolveQqCommandAction, } from "./QQSupport.js";
+import { handleQqC2CMessage, handleQqChannelMessage, handleQqGroupMessage, } from "./QQMessageHandler.js";
+import { EventType } from "../../../chat/channels/qq/types/QqChannel.js";
+/**
+ * QQ 平台适配器。
+ */
+export class QQBot extends BaseChatChannel {
+    appId;
+    appSecret;
+    useSandbox;
+    gateway;
+    inboundDedupeStore;
+    msgSeqByMessageKey = new Map();
+    botUserId = "";
+    botDisplayName = "";
+    constructor(context, appId, appSecret, useSandbox = false) {
+        super({ channel: "qq", context });
+        this.appId = appId;
+        this.appSecret = appSecret;
+        this.useSandbox = useSandbox;
+        this.inboundDedupeStore = new QqInboundDedupeStore({
+            rootPath: this.rootPath,
+            logger: this.logger,
+        });
+        this.gateway = new QQGatewayClient({
+            rootPath: this.rootPath,
+            logger: this.logger,
+            appId: this.appId,
+            appSecret: this.appSecret,
+            useSandbox: this.useSandbox,
+            captureConfig: getQqEventCaptureConfig(this.rootPath),
+            onDispatch: async (params) => {
+                await this.handleDispatch(params.eventType, params.data);
+            },
+        });
+    }
+    getChatKey(params) {
+        const chatType = typeof params.chatType === "string" && params.chatType
+            ? params.chatType
+            : "unknown";
+        return `qq-${chatType}-${params.chatId}`;
+    }
+    async sendTextToPlatform(params) {
+        const parsedMessage = parseChatMessageMarkup(String(params.text ?? ""));
+        if (parsedMessage.files.length > 0) {
+            throw new Error("QQ outbound attachment is not supported yet.");
+        }
+        const chatType = typeof params.chatType === "string" ? params.chatType : "";
+        const messageId = typeof params.messageId === "string" ? params.messageId : "";
+        if (!chatType || !messageId) {
+            throw new Error("QQ requires chatType + messageId to send a reply");
+        }
+        const key = `${chatType}:${params.chatId}:${messageId}`;
+        const nextSeq = (this.msgSeqByMessageKey.get(key) ?? 0) + 1;
+        this.msgSeqByMessageKey.set(key, nextSeq);
+        await this.gateway.sendMessage(params.chatId, chatType, messageId, parsedMessage.bodyText, nextSeq);
+    }
+    /**
+     * 读取 QQ 状态快照。
+     */
+    getExecutorStatus() {
+        const runtime = this.gateway.getExecutorStatus();
+        return {
+            ...runtime,
+            detail: {
+                ...runtime.detail,
+                appId: this.appId || null,
+                botName: this.botDisplayName || null,
+                botUserId: this.botUserId || null,
+                sandbox: this.useSandbox,
+            },
+        };
+    }
+    /**
+     * 执行 QQ 连通性测试。
+     */
+    async testConnection() {
+        const result = await this.gateway.testConnection();
+        const detail = result.detail && typeof result.detail === "object" && !Array.isArray(result.detail)
+            ? result.detail
+            : {};
+        return {
+            ...result,
+            detail: {
+                ...detail,
+                botName: this.botDisplayName || null,
+                botUserId: this.botUserId || null,
+            },
+        };
+    }
+    /**
+     * 启动机器人。
+     */
+    async start() {
+        if (!this.appId || !this.appSecret) {
+            this.logger.warn("QQ 机器人配置不完整（需要 appId 和 appSecret），跳过启动");
+            return;
+        }
+        this.logger.info("🤖 正在启动 QQ 机器人...");
+        this.logger.info(`   AppID: ${this.appId}`);
+        this.logger.info(`   沙箱模式: ${this.useSandbox ? "是" : "否"}`);
+        try {
+            await this.inboundDedupeStore.load();
+            await this.gateway.start();
+        }
+        catch (error) {
+            this.logger.error("启动 QQ Bot 失败", { error: String(error) });
+            await this.gateway.stop();
+        }
+    }
+    /**
+     * 停止机器人。
+     */
+    async stop() {
+        await this.gateway.stop();
+        this.logger.info("QQ Bot 已停止");
+    }
+    /**
+     * Dispatch 事件总入口。
+     */
+    async handleDispatch(eventType, data) {
+        this.logger.info(`收到事件: ${eventType}`);
+        switch (eventType) {
+            case EventType.READY:
+                this.captureReadyIdentity(data);
+                break;
+            case EventType.RESUMED:
+                this.logger.info("连接已恢复");
+                break;
+            case EventType.GROUP_AT_MESSAGE_CREATE:
+                await this.handleGroupMessage({
+                    eventType: EventType.GROUP_AT_MESSAGE_CREATE,
+                    data: data,
+                });
+                break;
+            case EventType.GROUP_MESSAGE_CREATE:
+                await this.handleGroupMessage({
+                    eventType: EventType.GROUP_MESSAGE_CREATE,
+                    data: data,
+                });
+                break;
+            case EventType.C2C_MESSAGE_CREATE:
+                await this.handleC2CMessage(data);
+                break;
+            case EventType.AT_MESSAGE_CREATE:
+                await this.handleChannelMessage(data);
+                break;
+            default:
+                this.logger.debug(`未处理的事件类型: ${eventType}`);
+        }
+    }
+    /**
+     * 捕获 READY 事件中的机器人身份信息。
+     */
+    captureReadyIdentity(data) {
+        const identity = extractQqReadyIdentity(data);
+        this.botDisplayName = identity.botDisplayName;
+        this.botUserId = identity.botUserId;
+        this.logger.info(`QQ Bot 已就绪，WS Context ID: ${identity.wsContextId}`);
+        this.logger.info(`用户: ${this.botDisplayName || "N/A"}`);
+    }
+    /**
+     * 处理群聊消息。
+     */
+    async handleGroupMessage(params) {
+        await handleQqGroupMessage(this.getMessageHandlerOptions(), params);
+    }
+    /**
+     * 处理 C2C 私聊消息。
+     */
+    async handleC2CMessage(data) {
+        await handleQqC2CMessage(this.getMessageHandlerOptions(), data);
+    }
+    /**
+     * 处理频道消息。
+     */
+    async handleChannelMessage(data) {
+        await handleQqChannelMessage(this.getMessageHandlerOptions(), data);
+    }
+    /**
+     * 构造 QQ 入站处理依赖。
+     */
+    getMessageHandlerOptions() {
+        return {
+            context: this.context,
+            rootPath: this.rootPath,
+            logger: this.logger,
+            getBotUserId: () => this.botUserId,
+            getChatKey: (params) => this.getChatKey(params),
+            observeIncomingAuthorization: async (params) => {
+                await this.observeIncomingAuthorization(params);
+            },
+            evaluateIncomingAuthorization: async (params) => await this.evaluateIncomingAuthorization(params),
+            sendAuthorizationText: async (params) => {
+                await this.sendAuthorizationText(params);
+            },
+            buildUnauthorizedBlockedText: (params) => this.buildUnauthorizedBlockedText(params),
+            shouldSkipDuplicatedInboundMessage: async (eventType, messageId) => await this.shouldSkipDuplicatedInboundMessage(eventType, messageId),
+            enqueueAuditMessage: async (params) => {
+                await this.enqueueAuditMessage(params);
+            },
+            handleCommand: async (params) => {
+                await this.handleCommand(params.chatId, params.chatType, params.messageId, params.command);
+            },
+            executeAndReply: async (params) => {
+                await this.executeAndReply(params.chatId, params.chatType, params.messageId, params.instructions, params.actor, params.chatTitle);
+            },
+            getAuthToken: async () => await this.gateway.getAuthToken(),
+        };
+    }
+    /**
+     * 入站去重检查。
+     */
+    async shouldSkipDuplicatedInboundMessage(eventType, messageId) {
+        const id = typeof messageId === "string" ? messageId.trim() : "";
+        if (!id)
+            return false;
+        const duplicated = await this.inboundDedupeStore.markAndCheckDuplicate({
+            eventType,
+            messageId: id,
+        });
+        if (!duplicated)
+            return false;
+        this.logger.info("忽略重复入站消息", {
+            eventType,
+            messageId: id,
+        });
+        return true;
+    }
+    /**
+     * 处理命令消息。
+     */
+    async handleCommand(chatId, chatType, messageId, command) {
+        this.logger.info(`收到命令: ${command}`);
+        const action = resolveQqCommandAction(command);
+        if (action.action === "clear_chat") {
+            await this.clearChatByTarget({
+                chatId,
+                chatType,
+            });
+        }
+        await this.gateway.sendMessage(chatId, chatType, messageId, action.responseText);
+    }
+    /**
+     * 执行指令并回复。
+     */
+    async executeAndReply(chatId, chatType, messageId, instructions, actor, chatTitle) {
+        try {
+            await this.enqueueMessage({
+                chatId,
+                text: instructions,
+                chatType,
+                messageId,
+                ...(actor?.userId ? { userId: actor.userId } : {}),
+                ...(actor?.username ? { username: actor.username } : {}),
+                ...(chatTitle ? { chatTitle } : {}),
+            });
+        }
+        catch (error) {
+            await this.gateway.sendMessage(chatId, chatType, messageId, `❌ 执行错误: ${String(error)}`, 1);
+        }
+    }
+}
+/**
+ * 创建 QQ 机器人实例。
+ */
+export async function createQQBot(config, context) {
+    if (!config.enabled || !config.appId || !config.appSecret) {
+        return null;
+    }
+    return new QQBot(context, config.appId, config.appSecret, config.sandbox || false);
+}
+//# sourceMappingURL=QQ.js.map

package/bin/chat/channels/qq/QQ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QQ.js","sourceRoot":"","sources":["../../../../src/chat/channels/qq/QQ.ts"],"names":[],"mappings":"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"}

package/bin/chat/channels/qq/QQEventCapture.d.ts

@@ -0,0 +1,22 @@
+/**
+ * QQEventCapture：QQ 原始网关事件落盘辅助。
+ *
+ * 关键点（中文）
+ * - 只负责“是否捕获”和“如何落盘”，不参与 QQ 主流程路由。
+ * - 开启后可帮助排查 QQ 字段缺失、事件结构差异、平台权限差异等问题。
+ */
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { QQEventCaptureConfig, QQGatewayPayload } from "../../../chat/channels/qq/types/QqChannel.js";
+/**
+ * 读取 QQ 原始事件捕获配置。
+ */
+export declare function getQqEventCaptureConfig(projectRoot: string): QQEventCaptureConfig;
+/**
+ * 捕获一条 QQ WebSocket 原始载荷。
+ */
+export declare function captureQqWsPayload(params: {
+    config: QQEventCaptureConfig;
+    logger: Logger;
+    payload: QQGatewayPayload;
+}): Promise<void>;
+//# sourceMappingURL=QQEventCapture.d.ts.map

package/bin/chat/channels/qq/QQEventCapture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QQEventCapture.d.ts","sourceRoot":"","sources":["../../../../src/chat/channels/qq/QQEventCapture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iDAAiD,CAAC;AAC9E,OAAO,KAAK,EAAE,oBAAoB,EAAsB,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAExH;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,CAyBjF;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gBAAgB,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB"}

package/bin/chat/channels/qq/QQEventCapture.js

@@ -0,0 +1,67 @@
+/**
+ * QQEventCapture：QQ 原始网关事件落盘辅助。
+ *
+ * 关键点（中文）
+ * - 只负责“是否捕获”和“如何落盘”，不参与 QQ 主流程路由。
+ * - 开启后可帮助排查 QQ 字段缺失、事件结构差异、平台权限差异等问题。
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * 读取 QQ 原始事件捕获配置。
+ */
+export function getQqEventCaptureConfig(projectRoot) {
+    const raw = String(process.env.SHIP_QQ_CAPTURE_EVENTS ?? "")
+        .trim()
+        .toLowerCase();
+    if (!raw || ["0", "false", "off", "no"].includes(raw)) {
+        return {
+            enabled: false,
+            mode: "dispatch",
+            dir: join(projectRoot, ".downcity", ".debug", "qq-events"),
+        };
+    }
+    const mode = raw === "all" ? "all" : raw === "dispatch" ? "dispatch" : "dispatch";
+    const dir = typeof process.env.SHIP_QQ_CAPTURE_DIR === "string" &&
+        process.env.SHIP_QQ_CAPTURE_DIR.trim()
+        ? process.env.SHIP_QQ_CAPTURE_DIR.trim()
+        : join(projectRoot, ".downcity", ".debug", "qq-events");
+    return {
+        enabled: true,
+        mode,
+        dir,
+    };
+}
+/**
+ * 捕获一条 QQ WebSocket 原始载荷。
+ */
+export async function captureQqWsPayload(params) {
+    if (!params.config.enabled)
+        return;
+    if (params.config.mode === "dispatch" && params.payload.op !== 0) {
+        return;
+    }
+    try {
+        const safeTag = sanitizeFileTag(`${String(params.payload.t ?? "N_A")}`);
+        const safeOp = sanitizeFileTag(`${String(params.payload.op ?? "unknown")}`);
+        const safeSeq = sanitizeFileTag(`${String(params.payload.s ?? "")}`);
+        const filename = `${Date.now()}_${safeOp}_${safeTag}${safeSeq ? `_${safeSeq}` : ""}.json`;
+        await mkdir(params.config.dir, { recursive: true });
+        await writeFile(join(params.config.dir, filename), JSON.stringify({
+            receivedAt: new Date().toISOString(),
+            payload: params.payload,
+        }, null, 2), "utf-8");
+    }
+    catch (error) {
+        params.logger.debug("QQ event capture failed (ignored)", {
+            error: String(error),
+        });
+    }
+}
+/**
+ * 把任意文本清洗成文件名安全片段。
+ */
+function sanitizeFileTag(input) {
+    return input.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 80) || "N_A";
+}
+//# sourceMappingURL=QQEventCapture.js.map

package/bin/chat/channels/qq/QQEventCapture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QQEventCapture.js","sourceRoot":"","sources":["../../../../src/chat/channels/qq/QQEventCapture.ts"],"names":[],"mappings":"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"}

package/bin/chat/channels/qq/QQGatewayAuth.d.ts

@@ -0,0 +1,119 @@
+/**
+ * QQ Gateway 鉴权与探活辅助函数。
+ *
+ * 关键点（中文）
+ * - Access Token、Gateway URL、HTTP 连通性测试都放在这里。
+ * - `QQGatewayClient` 只负责编排状态，不再直接内嵌所有 OpenAPI 请求细节。
+ */
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { ChatChannelTestResult } from "../../../chat/types/ChannelStatus.js";
+import type { QqGatewayRuntimeStatus } from "../../../chat/channels/qq/types/QqChannel.js";
+/**
+ * Access Token 获取结果。
+ */
+export interface QqAccessTokenResult {
+    /**
+     * 最新 access token。
+     */
+    accessToken: string;
+    /**
+     * token 过期时间戳（毫秒）。
+     */
+    accessTokenExpiresAtMs: number;
+}
+/**
+ * 获取 QQ Access Token 所需参数。
+ */
+export interface FetchQqAccessTokenParams {
+    /**
+     * 日志器。
+     */
+    logger: Logger;
+    /**
+     * 鉴权 API 基础地址。
+     */
+    authApiBase: string;
+    /**
+     * QQ appId。
+     */
+    appId: string;
+    /**
+     * QQ appSecret。
+     */
+    appSecret: string;
+    /**
+     * 当前缓存 token。
+     */
+    cachedAccessToken: string;
+    /**
+     * 当前缓存 token 过期时间。
+     */
+    cachedAccessTokenExpiresAtMs: number;
+}
+/**
+ * 获取 Gateway URL 所需参数。
+ */
+export interface FetchQqGatewayUrlParams {
+    /**
+     * 日志器。
+     */
+    logger: Logger;
+    /**
+     * OpenAPI 基础地址。
+     */
+    apiBase: string;
+    /**
+     * Bearer 鉴权头。
+     */
+    authToken: string;
+    /**
+     * 获取失败时使用的默认 ws 地址。
+     */
+    fallbackWsGateway: string;
+}
+/**
+ * QQ 连通性测试参数。
+ */
+export interface TestQqGatewayConnectionParams {
+    /**
+     * appId。
+     */
+    appId: string;
+    /**
+     * appSecret。
+     */
+    appSecret: string;
+    /**
+     * 是否沙箱环境。
+     */
+    useSandbox: boolean;
+    /**
+     * OpenAPI 基础地址。
+     */
+    apiBase: string;
+    /**
+     * 获取鉴权 token 的回调。
+     */
+    getAuthToken: () => Promise<string>;
+    /**
+     * 读取当前 runtime 状态的回调。
+     */
+    getExecutorStatus: () => QqGatewayRuntimeStatus;
+    /**
+     * 当探活发现异常时触发重连的回调。
+     */
+    requestReconnect: (reason: string, delayMs?: number) => void;
+}
+/**
+ * 获取并刷新 QQ Access Token。
+ */
+export declare function fetchQqAccessToken(params: FetchQqAccessTokenParams): Promise<QqAccessTokenResult>;
+/**
+ * 获取 QQ Gateway 地址。
+ */
+export declare function fetchQqGatewayUrl(params: FetchQqGatewayUrlParams): Promise<string>;
+/**
+ * 执行 QQ HTTP 连通性测试。
+ */
+export declare function testQqGatewayConnection(params: TestQqGatewayConnectionParams): Promise<ChatChannelTestResult>;
+//# sourceMappingURL=QQGatewayAuth.d.ts.map

package/bin/chat/channels/qq/QQGatewayAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QQGatewayAuth.d.ts","sourceRoot":"","sources":["../../../../src/chat/channels/qq/QQGatewayAuth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iDAAiD,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,4BAA4B,EAAE,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,YAAY,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC;;OAEG;IACH,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;IAChD;;OAEG;IACH,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CA2D9B;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAoCjB;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,qBAAqB,CAAC,CA2FhC"}