@downcity/agent 1.1.23 → 1.1.32

package/src/service/builtins/chat/channels/qq/QQMessageHandler.ts

@@ -1,465 +0,0 @@
-/**
- * QQ 入站消息处理器。
- *
- * 关键点（中文）
- * - 负责 group / c2c / channel 三类入站消息的授权、去重、审计与执行入队。
- * - 不直接持有 `QQBot` 实例；所有副作用通过显式函数注入。
- * - `QQBot` 因此只保留渠道生命周期、dispatch 分流、发送与命令处理。
- */
-
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type {
-  ChannelChatKeyParams,
-  IncomingAuthorizationParams,
-  IncomingAuthorizationResult,
-} from "@/service/builtins/chat/channels/BaseChatChannel.js";
-import type { ChannelUserMessageMeta } from "@/service/builtins/chat/channels/BaseChatChannelSupport.js";
-import {
-  buildQqAuditText,
-  extractQqAuthorIdentity,
-  extractQqInboundAttachments,
-  extractQqTextContent,
-  resolveQqInboundChatTitle,
-  stripQqBotMention,
-} from "./QQInbound.js";
-import {
-  buildQqInboundInstructions,
-  resolveQqC2cChatId,
-  resolveQqGroupChatId,
-} from "./QQSupport.js";
-import type { QQMessageData } from "./types/QqChannel.js";
-import { EventType } from "./types/QqChannel.js";
-
-/**
- * QQ 消息作者身份。
- */
-export type QqMessageActor = {
-  /**
-   * QQ 用户 ID / openid。
-   */
-  userId?: string;
-  /**
-   * QQ 用户展示名。
-   */
-  username?: string;
-};
-
-/**
- * QQ 入站消息处理依赖。
- */
-export interface QQMessageHandlerOptions {
-  /**
-   * 当前 agent context。
-   */
-  context: AgentContext;
-  /**
-   * 项目根目录。
-   */
-  rootPath: string;
-  /**
-   * 日志器。
-   */
-  logger: Logger;
-  /**
-   * 当前 bot 用户 ID。
-   */
-  getBotUserId(): string;
-  /**
-   * 计算 channel chatKey。
-   */
-  getChatKey(params: ChannelChatKeyParams): string;
-  /**
-   * 入站主体观测。
-   */
-  observeIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<void>;
-  /**
-   * 入站授权判定。
-   */
-  evaluateIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<IncomingAuthorizationResult>;
-  /**
-   * 发送授权失败提示。
-   */
-  sendAuthorizationText(params: {
-    chatId: string;
-    text: string;
-    chatType?: string;
-  }): Promise<void>;
-  /**
-   * 构建授权失败提示文案。
-   */
-  buildUnauthorizedBlockedText(params?: {
-    userId?: string;
-    chatId?: string;
-    chatType?: string;
-  }): string;
-  /**
-   * 入站去重判断。
-   */
-  shouldSkipDuplicatedInboundMessage(
-    eventType: string,
-    messageId: string | undefined,
-  ): Promise<boolean>;
-  /**
-   * Audit 队列写入。
-   */
-  enqueueAuditMessage(params: {
-    chatId: string;
-    messageId?: string;
-    userId?: string;
-    text: string;
-    meta?: ChannelUserMessageMeta;
-  }): Promise<void>;
-  /**
-   * 命令处理。
-   */
-  handleCommand(params: {
-    chatId: string;
-    chatType: string;
-    messageId: string;
-    command: string;
-  }): Promise<void>;
-  /**
-   * 执行入队。
-   */
-  executeAndReply(params: {
-    chatId: string;
-    chatType: string;
-    messageId: string;
-    instructions: string;
-    actor?: QqMessageActor;
-    chatTitle?: string;
-  }): Promise<void>;
-  /**
-   * QQ access token 获取函数，用于入站附件下载。
-   */
-  getAuthToken(): Promise<string>;
-}
-
-/**
- * 处理群聊消息。
- */
-export async function handleQqGroupMessage(
-  options: QQMessageHandlerOptions,
-  params: {
-    eventType: string;
-    data: QQMessageData;
-  },
-): Promise<void> {
-  const eventType = String(params.eventType || "").trim();
-  const data = params.data;
-  const messageId =
-    typeof data.id === "string" ? data.id.trim() : String(data.id || "").trim();
-  if (!messageId) return;
-
-  const groupId = resolveQqGroupChatId(data);
-  if (!groupId) {
-    options.logger.warn("QQ 群消息缺少 groupId，已忽略", {
-      eventType: eventType || EventType.GROUP_MESSAGE_CREATE,
-      messageId,
-    });
-    return;
-  }
-
-  await handleQqInboundMessage(options, {
-    eventType: eventType || EventType.GROUP_MESSAGE_CREATE,
-    chatId: groupId,
-    chatType: "group",
-    data,
-  });
-}
-
-/**
- * 处理 C2C 私聊消息。
- */
-export async function handleQqC2CMessage(
-  options: QQMessageHandlerOptions,
-  data: QQMessageData,
-): Promise<void> {
-  const messageId =
-    typeof data.id === "string" ? data.id.trim() : String(data.id || "").trim();
-  if (!messageId) return;
-
-  const actor = extractQqAuthorIdentity(data.author, data);
-  const chatId = resolveQqC2cChatId({
-    data,
-    actorUserId: actor.userId,
-  });
-  if (!chatId) {
-    options.logger.warn("QQ C2C 消息缺少 userId，已忽略", {
-      eventType: EventType.C2C_MESSAGE_CREATE,
-      messageId,
-    });
-    return;
-  }
-
-  await handleQqInboundMessage(options, {
-    eventType: EventType.C2C_MESSAGE_CREATE,
-    chatId,
-    chatType: "c2c",
-    data,
-    actor,
-  });
-}
-
-/**
- * 处理频道消息。
- */
-export async function handleQqChannelMessage(
-  options: QQMessageHandlerOptions,
-  data: QQMessageData,
-): Promise<void> {
-  const { id: messageId, channel_id: channelId, content, author } = data;
-  if (!channelId || !messageId) return;
-  const chatType = "channel";
-  if (
-    await options.shouldSkipDuplicatedInboundMessage(
-      EventType.AT_MESSAGE_CREATE,
-      messageId,
-    )
-  ) {
-    return;
-  }
-
-  const userMessage = extractQqTextContent(String(content || ""));
-  const incomingAttachments = extractQqInboundAttachments(data);
-  const actor = extractQqAuthorIdentity(author, data);
-  const chatTitle = resolveQqInboundChatTitle({
-    chatType,
-    data,
-    actorName: actor.username,
-  });
-
-  await options.observeIncomingAuthorization({
-    chatId: channelId,
-    chatType,
-    chatTitle,
-    userId: actor.userId,
-    username: actor.username,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
-    chatId: channelId,
-    chatType,
-    chatTitle,
-    userId: actor.userId,
-    username: actor.username,
-  });
-  if (authResult.decision !== "allow") return;
-
-  const botUserId = options.getBotUserId();
-  if (actor.userId && botUserId && actor.userId === botUserId) {
-    options.logger.debug("忽略机器人自身消息（channel）", {
-      messageId,
-      channelId,
-      botUserId,
-    });
-    return;
-  }
-
-  options.logger.info(`收到频道消息 [${channelId}]: ${userMessage}`);
-
-  if (userMessage.startsWith("/")) {
-    await options.handleCommand({
-      chatId: channelId,
-      chatType: "channel",
-      messageId,
-      command: userMessage,
-    });
-    return;
-  }
-
-  const instructions = await buildQqInboundInstructions({
-    context: options.context,
-    rootPath: options.rootPath,
-    chatId: channelId,
-    chatKey: options.getChatKey({ chatId: channelId, chatType }),
-    messageId,
-    userMessage,
-    attachments: incomingAttachments,
-    getAuthToken: () => options.getAuthToken(),
-  });
-  if (!instructions) return;
-
-  await options.executeAndReply({
-    chatId: channelId,
-    chatType: "channel",
-    messageId,
-    instructions,
-    actor,
-    chatTitle,
-  });
-}
-
-/**
- * QQ group / c2c 入站主流程。
- */
-async function handleQqInboundMessage(
-  options: QQMessageHandlerOptions,
-  params: {
-    eventType: string;
-    chatId: string;
-    chatType: "group" | "c2c";
-    data: QQMessageData;
-    actor?: QqMessageActor;
-  },
-): Promise<void> {
-  const eventType = String(params.eventType || "").trim();
-  const chatId = String(params.chatId || "").trim();
-  const messageId =
-    typeof params.data.id === "string"
-      ? params.data.id.trim()
-      : String(params.data.id || "").trim();
-  if (!chatId || !messageId) return;
-
-  if (await options.shouldSkipDuplicatedInboundMessage(eventType, messageId)) {
-    return;
-  }
-
-  const actor = params.actor || extractQqAuthorIdentity(params.data.author, params.data);
-  const chatType = params.chatType;
-  if (!actor.userId) {
-    options.logger.warn("QQ 入站消息缺少发送者 userId，已忽略", {
-      eventType,
-      chatId,
-      chatType,
-      messageId,
-    });
-    return;
-  }
-
-  const chatTitle = resolveQqInboundChatTitle({
-    chatType,
-    data: params.data,
-    actorName: actor.username,
-  });
-  const isGroup = chatType === "group";
-  const chatKey = options.getChatKey({ chatId, chatType });
-  const rawContent = String(params.data.content || "");
-  const incomingAttachments = extractQqInboundAttachments(params.data);
-  const hasIncomingAttachment = incomingAttachments.length > 0;
-  const botUserId = options.getBotUserId();
-  const cleanedText = isGroup
-    ? stripQqBotMention(rawContent, botUserId)
-    : extractQqTextContent(rawContent);
-
-  await options.observeIncomingAuthorization({
-    chatId,
-    chatType,
-    chatTitle,
-    userId: actor.userId,
-    username: actor.username,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
-    chatId,
-    chatType,
-    chatTitle,
-    userId: actor.userId,
-    username: actor.username,
-  });
-  if (authResult.decision !== "allow") {
-    if (!isGroup) {
-      await options.sendAuthorizationText({
-        chatId,
-        chatType,
-        text: options.buildUnauthorizedBlockedText({
-          chatId,
-          chatType,
-          userId: actor.userId,
-        }),
-      });
-    }
-    return;
-  }
-
-  const enqueueAudit = async (opts: { reason: string; kind?: string }): Promise<void> => {
-    await options.enqueueAuditMessage({
-      chatId,
-      messageId,
-      userId: actor.userId,
-      text: buildQqAuditText({
-        rawContent,
-        cleanedText,
-        hasIncomingAttachment,
-      }),
-      meta: {
-        chatType,
-        username: actor.username,
-        chatTitle,
-        eventType,
-        reason: opts.reason,
-        ...(opts.kind ? { kind: opts.kind } : {}),
-      },
-    });
-  };
-
-  if (actor.userId && botUserId && actor.userId === botUserId) {
-    if (isGroup) {
-      await enqueueAudit({ reason: "bot_originated" });
-    }
-    options.logger.debug("忽略机器人自身消息", {
-      messageId,
-      chatId,
-      chatType,
-      botUserId,
-    });
-    return;
-  }
-
-  options.logger.info(`收到 ${chatType} 消息 [${chatId}]: ${cleanedText}`);
-
-  if (!rawContent && !hasIncomingAttachment) {
-    if (isGroup) {
-      await enqueueAudit({ reason: "empty_payload" });
-    }
-    return;
-  }
-
-  if (cleanedText.startsWith("/")) {
-    await enqueueAudit({
-      reason: "command_received",
-      kind: "command",
-    });
-    await options.handleCommand({
-      chatId,
-      chatType,
-      messageId,
-      command: cleanedText,
-    });
-    return;
-  }
-
-  if (!cleanedText && !hasIncomingAttachment) {
-    await enqueueAudit({ reason: "empty_after_clean" });
-    return;
-  }
-
-  const instructions = await buildQqInboundInstructions({
-    context: options.context,
-    rootPath: options.rootPath,
-    chatId,
-    chatKey,
-    messageId,
-    userMessage: cleanedText,
-    attachments: incomingAttachments,
-    getAuthToken: () => options.getAuthToken(),
-  });
-  if (!instructions) {
-    await enqueueAudit({ reason: "empty_after_build" });
-    return;
-  }
-
-  await options.executeAndReply({
-    chatId,
-    chatType,
-    messageId,
-    instructions,
-    actor,
-    chatTitle,
-  });
-}

package/src/service/builtins/chat/channels/qq/QQSupport.ts

@@ -1,263 +0,0 @@
-/**
- * QQ 渠道辅助逻辑。
- *
- * 关键点（中文）
- * - 把 READY 身份解析、命令映射、入站增强组装等从 `QQ.ts` 抽离。
- * - 这些逻辑尽量保持纯函数或最小依赖，便于单测与复用。
- */
-
-import { buildChatInboundText, augmentChatInboundInput } from "@/service/builtins/chat/runtime/InboundAugment.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { JsonObject } from "@/types/common/Json.js";
-import type { QQMessageData, QQReadyUser } from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
-import type { QqIncomingAttachment } from "@/service/builtins/chat/types/QqVoice.js";
-import { resolveQqAttachmentLocalPath } from "./VoiceInput.js";
-
-/**
- * QQ READY 身份快照。
- */
-export interface QqReadyIdentity {
-  /**
-   * 当前 ws context id。
-   */
-  wsContextId: string;
-  /**
-   * 机器人展示名。
-   */
-  botDisplayName: string;
-  /**
-   * 机器人用户主键。
-   */
-  botUserId: string;
-}
-
-/**
- * QQ 命令动作定义。
- */
-export interface QqCommandAction {
-  /**
-   * 动作类型。
-   */
-  action: "reply_only" | "clear_chat";
-  /**
-   * 回复文本。
-   */
-  responseText: string;
-}
-
-/**
- * QQ 入站增强组装参数。
- */
-export interface BuildQqInboundInstructionsParams {
-  /**
-   * 当前执行上下文。
-   */
-  context: AgentContext;
-  /**
-   * 项目根目录。
-   */
-  rootPath: string;
-  /**
-   * 平台 chatId。
-   */
-  chatId: string;
-  /**
-   * chat queue key。
-   */
-  chatKey: string;
-  /**
-   * 当前消息 id。
-   */
-  messageId: string;
-  /**
-   * 用户文本。
-   */
-  userMessage: string;
-  /**
-   * 附件列表。
-   */
-  attachments: QqIncomingAttachment[];
-  /**
-   * 获取 gateway 鉴权头的回调。
-   */
-  getAuthToken: () => Promise<string>;
-}
-
-/**
- * 解析 READY 事件中的机器人身份信息。
- */
-export function extractQqReadyIdentity(data: JsonObject): QqReadyIdentity {
-  const readyUser =
-    data.user && typeof data.user === "object" && !Array.isArray(data.user)
-      ? (data.user as QQReadyUser)
-      : undefined;
-  return {
-    wsContextId: typeof data.context_id === "string" ? data.context_id : "",
-    botDisplayName:
-      [
-        readyUser?.username,
-        readyUser?.nickname,
-        readyUser?.name,
-        readyUser?.bot_name,
-        readyUser?.user?.username,
-        readyUser?.user?.nickname,
-        readyUser?.user?.name,
-      ]
-        .map((value) => (typeof value === "string" ? value.trim() : ""))
-        .find(Boolean) || "",
-    botUserId:
-      typeof readyUser?.id === "string"
-        ? readyUser.id.trim()
-        : typeof readyUser?.user_id === "string"
-          ? readyUser.user_id.trim()
-          : typeof readyUser?.user_openid === "string"
-            ? readyUser.user_openid.trim()
-            : typeof readyUser?.openid === "string"
-              ? readyUser.openid.trim()
-              : "",
-  };
-}
-
-/**
- * 解析 QQ 命令动作。
- */
-export function resolveQqCommandAction(command: string): QqCommandAction {
-  const normalized = String(command || "").toLowerCase().trim();
-  const head = normalized.split(" ")[0] || "";
-  switch (head) {
-    case "/help":
-    case "/帮助":
-      return {
-        action: "reply_only",
-        responseText: `🤖 Downcity Bot
-
-可用命令:
-- /help 或 /帮助 - 查看帮助信息
-- /status 或 /状态 - 查看 Agent 状态
-- /tasks 或 /任务 - 查看任务列表
-- /clear 或 /清除 - 彻底删除当前对话
-- <任意消息> - 执行指令`,
-      };
-    case "/status":
-    case "/状态":
-      return {
-        action: "reply_only",
-        responseText: "📊 Agent 状态: 运行中\n任务数: 0\n待审批: 0",
-      };
-    case "/tasks":
-    case "/任务":
-      return {
-        action: "reply_only",
-        responseText: "📋 任务列表\n暂无任务",
-      };
-    case "/clear":
-    case "/清除":
-      return {
-        action: "clear_chat",
-        responseText: "✅ 对话已彻底删除",
-      };
-    default:
-      return {
-        action: "reply_only",
-        responseText: `未知命令: ${command}\n输入 /help 查看可用命令`,
-      };
-  }
-}
-
-/**
- * 解析 QQ 群消息的 chatId。
- */
-export function resolveQqGroupChatId(data: QQMessageData): string {
-  return [
-    data.group_openid,
-    data.group_id,
-    data.group_code,
-    data.group_uin,
-    data.channel_id,
-    data.guild_id,
-  ]
-    .map((value) => (typeof value === "string" ? value.trim() : ""))
-    .find(Boolean) || "";
-}
-
-/**
- * 解析 QQ C2C 消息的 chatId。
- */
-export function resolveQqC2cChatId(params: {
-  data: QQMessageData;
-  actorUserId?: string;
-}): string {
-  const { data, actorUserId } = params;
-  return [
-    actorUserId,
-    data.user_openid,
-    data.openid,
-    data.author_id,
-    data.author?.user_openid,
-    data.author?.member_openid,
-    data.author?.openid,
-    data.author?.id,
-    data.author?.user_id,
-    data.author?.user?.user_openid,
-    data.author?.user?.openid,
-    data.author?.user?.id,
-    data.author?.user?.user_id,
-  ]
-    .map((value) => (typeof value === "string" ? value.trim() : ""))
-    .find(Boolean) || "";
-}
-
-/**
- * 构造 QQ 入站执行指令（文本 + 语音转写增强）。
- */
-export async function buildQqInboundInstructions(
-  params: BuildQqInboundInstructionsParams,
-): Promise<string> {
-  const text = String(params.userMessage || "").trim();
-  const authToken = await params.getAuthToken();
-  const resolvedAttachments = await Promise.all(
-    params.attachments.map(async (attachment) => {
-      const base = {
-        channel: "qq" as const,
-        kind: attachment.kind,
-        ...(attachment.fileName ? { fileName: attachment.fileName } : {}),
-        ...(attachment.contentType ? { contentType: attachment.contentType } : {}),
-        ...(attachment.attachmentId ? { attachmentId: attachment.attachmentId } : {}),
-      };
-      if (attachment.kind !== "voice" && attachment.kind !== "audio") {
-        return {
-          ...base,
-          ...(attachment.localPath ? { path: attachment.localPath } : {}),
-        };
-      }
-      try {
-        const localPath = await resolveQqAttachmentLocalPath({
-          rootPath: params.rootPath,
-          attachment,
-          authToken,
-        });
-        return {
-          ...base,
-          ...(localPath ? { path: localPath } : {}),
-        };
-      } catch {
-        return base;
-      }
-    }),
-  );
-
-  return buildChatInboundText(
-    await augmentChatInboundInput({
-      context: params.context,
-      input: {
-        channel: "qq",
-        chatId: params.chatId,
-        chatKey: params.chatKey,
-        messageId: params.messageId,
-        rootPath: params.rootPath,
-        bodyText: text || undefined,
-        attachments: resolvedAttachments,
-      },
-    }),
-  );
-}