@downcity/agent 1.1.10 → 1.1.12

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

@@ -0,0 +1,176 @@
+/**
+ * QQ Gateway 协议处理。
+ *
+ * 关键点（中文）
+ * - 只负责 Gateway op code 的协议路由与 Identify payload 构造。
+ * - 不持有 WebSocket 生命周期状态，所有状态写入通过回调交回 `QQGatewayClient`。
+ * - 这样 client 保持单一状态源，协议细节也不会继续挤在连接编排类里。
+ */
+
+import type WebSocket from "ws";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type {
+  QQGatewayPayload,
+  QqDispatchHandler,
+} from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
+import { EventType, OpCode } from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
+
+/**
+ * Gateway payload 处理参数。
+ */
+export interface HandleQqGatewayPayloadParams {
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * 当前 payload。
+   */
+  payload: QQGatewayPayload;
+  /**
+   * 记录服务端序列号。
+   */
+  setLastSeq(seq: number): void;
+  /**
+   * 启动心跳。
+   */
+  startHeartbeat(intervalMs: number): void;
+  /**
+   * 发送 Identify。
+   */
+  sendIdentify(): Promise<void>;
+  /**
+   * 标记 READY。
+   */
+  markReady(contextId: string): void;
+  /**
+   * 标记 RESUMED。
+   */
+  markResumed(): void;
+  /**
+   * 标记心跳 ACK。
+   */
+  markHeartbeatAck(): void;
+  /**
+   * 清理 access token 缓存。
+   */
+  clearAccessTokenCache(): void;
+  /**
+   * 触发 socket 自愈关闭。
+   */
+  closeSocketForRecovery(reason: string): void;
+  /**
+   * Dispatch 事件回调。
+   */
+  onDispatch(params: QqDispatchHandler): Promise<void>;
+}
+
+/**
+ * Identify 发送参数。
+ */
+export interface SendQqGatewayIdentifyParams {
+  /**
+   * 当前 socket。
+   */
+  socket: WebSocket | null;
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * 获取鉴权 token。
+   */
+  getAuthToken(): Promise<string>;
+}
+
+/**
+ * 处理 QQ Gateway payload。
+ */
+export async function handleQqGatewayPayload(
+  params: HandleQqGatewayPayloadParams,
+): Promise<void> {
+  const { op, d, s, t } = params.payload;
+  if (s) {
+    params.setLastSeq(s);
+  }
+
+  switch (op) {
+    case OpCode.Hello: {
+      const heartbeatIntervalMs =
+        typeof d?.heartbeat_interval === "number" ? d.heartbeat_interval : 30000;
+      params.startHeartbeat(heartbeatIntervalMs);
+      await params.sendIdentify();
+      break;
+    }
+    case OpCode.Dispatch: {
+      const eventType = String(t || "");
+      if (eventType === EventType.READY) {
+        params.markReady(typeof d?.context_id === "string" ? d.context_id : "");
+      } else if (eventType === EventType.RESUMED) {
+        params.markResumed();
+      }
+      await params.onDispatch({
+        eventType,
+        data: d || {},
+      });
+      break;
+    }
+    case OpCode.HeartbeatAck:
+      params.markHeartbeatAck();
+      params.logger.debug("收到心跳响应");
+      break;
+    case OpCode.Reconnect:
+      params.logger.warn("服务端要求重连");
+      params.closeSocketForRecovery("server_reconnect_opcode");
+      break;
+    case OpCode.InvalidContext:
+      params.logger.error("无效的 Context，需要重新鉴权");
+      params.clearAccessTokenCache();
+      setTimeout(async () => {
+        try {
+          await params.sendIdentify();
+        } catch (error) {
+          params.logger.error("重新鉴权失败", { error: String(error) });
+        }
+      }, 2000);
+      break;
+  }
+}
+
+/**
+ * 发送 QQ Gateway Identify。
+ */
+export async function sendQqGatewayIdentify(
+  params: SendQqGatewayIdentifyParams,
+): Promise<void> {
+  const authToken = await params.getAuthToken();
+  const intents = getQqGatewayIntents();
+  params.logger.info(`发送鉴权请求 (Identify)，intents: ${intents}`);
+
+  const identifyPayload = {
+    op: OpCode.Identify,
+    d: {
+      token: authToken,
+      intents,
+      shard: [0, 1],
+      properties: {
+        $os: "linux",
+        $browser: "downcity",
+        $device: "downcity",
+      },
+    },
+  };
+
+  params.logger.debug(`Identify payload: ${JSON.stringify(identifyPayload)}`);
+  params.socket?.send(JSON.stringify(identifyPayload));
+  params.logger.info("已发送鉴权请求");
+}
+
+/**
+ * 获取订阅事件位掩码。
+ */
+function getQqGatewayIntents(): number {
+  const GROUP_AND_C2C_EVENT = 1 << 25;
+  const AUDIO_ACTION = 1 << 29;
+  return GROUP_AND_C2C_EVENT | AUDIO_ACTION;
+}

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

@@ -7,7 +7,7 @@
  */
 
 import type { RawData } from "ws";
-import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { QQGatewayPayload, QqGatewayRuntimeStatus } from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
 import type {
   QqGatewayHeartbeatState,

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

@@ -7,7 +7,7 @@
  * - 具体“授权、入队、执行、回发”仍由 QQBot 负责编排。
  */
 
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { QqIncomingAttachment } from "@/service/builtins/chat/types/QqVoice.js";
 import type { QqActorIdentity, QQAuthor, QQMessageData } from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
 import { extractQqIncomingAttachments } from "./VoiceInput.js";

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

@@ -0,0 +1,465 @@
+/**
+ * QQ 入站消息处理器。
+ *
+ * 关键点（中文）
+ * - 负责 group / c2c / channel 三类入站消息的授权、去重、审计与执行入队。
+ * - 不直接持有 `QQBot` 实例；所有副作用通过显式函数注入。
+ * - `QQBot` 因此只保留渠道生命周期、dispatch 分流、发送与命令处理。
+ */
+
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { AgentContext } from "@/runtime/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/QQSendSupport.ts

@@ -6,7 +6,7 @@
  * - `QQGatewayClient` 只调用这些函数，不再内嵌大段重试细节。
  */
 
-import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 
 /**
  * 解析 QQ API 业务错误文本。

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

@@ -7,8 +7,8 @@
  */
 
 import { buildChatInboundText, augmentChatInboundInput } from "@/service/builtins/chat/runtime/InboundAugment.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { AgentContext } from "@/runtime/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";

package/src/service/builtins/chat/channels/qq/types/QqChannel.ts

@@ -3,11 +3,11 @@
  *
  * 关键点（中文）
  * - 这里集中放 QQ 渠道的网关载荷、消息结构、状态快照等共享契约。
- * - `services/chat/channels/qq/*` 只消费这些类型，不再在实现文件里内联大段局部类型。
+ * - `service/builtins/chat/channels/qq/*` 只消费这些类型，不再在实现文件里内联大段局部类型。
  * - 字段命名尽量保持与 QQ 官方事件/接口原始字段一致，降低映射心智负担。
  */
 
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 
 /**
  * QQ 渠道配置。