@downcity/agent 1.1.35 → 1.1.51

package/src/plugin/builtins/chat/channels/qq/QQ.ts

@@ -1,398 +0,0 @@
-/**
- * QQ 渠道门面。
- *
- * 关键点（中文）
- * - `QQBot` 只保留渠道层编排职责：入站授权、命令处理、消息入队、回复调度。
- * - Gateway 连接、自愈重连、消息回发已经下沉到 `QQGatewayClient`。
- * - 文本清洗、作者识别、标题解析、附件宽松提取已经下沉到 `QQInbound`。
- * - READY 身份解析、命令映射、入站增强组装已经下沉到 `QQSupport`。
- */
-
-import { BaseChatChannel } from "@/plugin/builtins/chat/channels/BaseChatChannel.js";
-import { parseChatMessageMarkup } from "@/plugin/builtins/chat/runtime/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,
-  type QQMessageHandlerOptions,
-  type QqMessageActor,
-} from "./QQMessageHandler.js";
-import type {
-  ChannelChatKeyParams,
-  ChannelSendTextParams,
-} from "@/plugin/builtins/chat/channels/BaseChatChannel.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { JsonObject } from "@/types/common/Json.js";
-import type { ChatChannelTestResult } from "@/plugin/builtins/chat/types/ChannelStatus.js";
-import type { QQConfig, QQMessageData } from "@/plugin/builtins/chat/channels/qq/types/QqChannel.js";
-import { EventType } from "@/plugin/builtins/chat/channels/qq/types/QqChannel.js";
-
-/**
- * QQ 平台适配器。
- */
-export class QQBot extends BaseChatChannel {
-  private readonly appId: string;
-  private readonly appSecret: string;
-  private readonly useSandbox: boolean;
-  private readonly gateway: QQGatewayClient;
-  private readonly inboundDedupeStore: QqInboundDedupeStore;
-  private readonly msgSeqByMessageKey: Map<string, number> = new Map();
-  private botUserId = "";
-  private botDisplayName = "";
-
-  constructor(
-    context: AgentContext,
-    appId: string,
-    appSecret: string,
-    useSandbox: boolean = 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);
-      },
-    });
-  }
-
-  protected getChatKey(params: ChannelChatKeyParams): string {
-    const chatType =
-      typeof params.chatType === "string" && params.chatType
-        ? params.chatType
-        : "unknown";
-    return `qq-${chatType}-${params.chatId}`;
-  }
-
-  protected async sendTextToPlatform(
-    params: ChannelSendTextParams,
-  ): Promise<void> {
-    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(): {
-    running: boolean;
-    linkState: "connected" | "disconnected" | "unknown";
-    statusText: string;
-    detail: Record<string, string | number | boolean | null>;
-  } {
-    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(): Promise<ChatChannelTestResult> {
-    const result = await this.gateway.testConnection();
-    const detail =
-      result.detail && typeof result.detail === "object" && !Array.isArray(result.detail)
-        ? (result.detail as Record<string, unknown>)
-        : {};
-    return {
-      ...result,
-      detail: {
-        ...detail,
-        botName: this.botDisplayName || null,
-        botUserId: this.botUserId || null,
-      },
-    };
-  }
-
-  /**
-   * 启动机器人。
-   */
-  async start(): Promise<void> {
-    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(): Promise<void> {
-    await this.gateway.stop();
-    this.logger.info("QQ Bot 已停止");
-  }
-
-  /**
-   * Dispatch 事件总入口。
-   */
-  private async handleDispatch(
-    eventType: string,
-    data: JsonObject,
-  ): Promise<void> {
-    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 as QQMessageData,
-        });
-        break;
-      case EventType.GROUP_MESSAGE_CREATE:
-        await this.handleGroupMessage({
-          eventType: EventType.GROUP_MESSAGE_CREATE,
-          data: data as QQMessageData,
-        });
-        break;
-      case EventType.C2C_MESSAGE_CREATE:
-        await this.handleC2CMessage(data as QQMessageData);
-        break;
-      case EventType.AT_MESSAGE_CREATE:
-        await this.handleChannelMessage(data as QQMessageData);
-        break;
-      default:
-        this.logger.debug(`未处理的事件类型: ${eventType}`);
-    }
-  }
-
-  /**
-   * 捕获 READY 事件中的机器人身份信息。
-   */
-  private captureReadyIdentity(data: JsonObject): void {
-    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"}`);
-  }
-
-  /**
-   * 处理群聊消息。
-   */
-  private async handleGroupMessage(params: {
-    eventType: string;
-    data: QQMessageData;
-  }): Promise<void> {
-    await handleQqGroupMessage(this.getMessageHandlerOptions(), params);
-  }
-
-  /**
-   * 处理 C2C 私聊消息。
-   */
-  private async handleC2CMessage(data: QQMessageData): Promise<void> {
-    await handleQqC2CMessage(this.getMessageHandlerOptions(), data);
-  }
-
-  /**
-   * 处理频道消息。
-   */
-  private async handleChannelMessage(data: QQMessageData): Promise<void> {
-    await handleQqChannelMessage(this.getMessageHandlerOptions(), data);
-  }
-
-  /**
-   * 构造 QQ 入站处理依赖。
-   */
-  private getMessageHandlerOptions(): QQMessageHandlerOptions {
-    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(),
-    };
-  }
-
-  /**
-   * 入站去重检查。
-   */
-  private async shouldSkipDuplicatedInboundMessage(
-    eventType: string,
-    messageId: string | undefined,
-  ): Promise<boolean> {
-    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;
-  }
-
-  /**
-   * 处理命令消息。
-   */
-  private async handleCommand(
-    chatId: string,
-    chatType: string,
-    messageId: string,
-    command: string,
-  ): Promise<void> {
-    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);
-  }
-
-  /**
-   * 执行指令并回复。
-   */
-  private async executeAndReply(
-    chatId: string,
-    chatType: string,
-    messageId: string,
-    instructions: string,
-    actor?: QqMessageActor,
-    chatTitle?: string,
-  ): Promise<void> {
-    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: QQConfig,
-  context: AgentContext,
-): Promise<QQBot | null> {
-  if (!config.enabled || !config.appId || !config.appSecret) {
-    return null;
-  }
-
-  return new QQBot(
-    context,
-    config.appId,
-    config.appSecret,
-    config.sandbox || false,
-  );
-}

package/src/plugin/builtins/chat/channels/qq/QQEventCapture.ts

@@ -1,88 +0,0 @@
-/**
- * QQEventCapture：QQ 原始网关事件落盘辅助。
- *
- * 关键点（中文）
- * - 只负责“是否捕获”和“如何落盘”，不参与 QQ 主流程路由。
- * - 开启后可帮助排查 QQ 字段缺失、事件结构差异、平台权限差异等问题。
- */
-
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { QQEventCaptureConfig, QQEventCaptureMode, QQGatewayPayload } from "@/plugin/builtins/chat/channels/qq/types/QqChannel.js";
-
-/**
- * 读取 QQ 原始事件捕获配置。
- */
-export function getQqEventCaptureConfig(projectRoot: string): QQEventCaptureConfig {
-  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: QQEventCaptureMode =
-    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: {
-  config: QQEventCaptureConfig;
-  logger: Logger;
-  payload: QQGatewayPayload;
-}): Promise<void> {
-  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: string): string {
-  return input.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 80) || "N_A";
-}