@downcity/agent 1.1.25 → 1.1.32

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

@@ -0,0 +1,137 @@
+/**
+ * QQ Bot 信息探测实现。
+ *
+ * 关键点（中文）
+ * - 先校验 appId/appSecret 可换取 access token。
+ * - 再验证 gateway 可达，并尝试读取 `users/@me`。
+ */
+
+import type {
+  ChatBotInfoCredentialInput,
+  ChatBotInfoResult,
+  ChatChannelBotInfoProvider,
+} from "@/plugin/builtins/chat/types/BotInfo.js";
+
+function pickFirstNonEmpty(inputs: unknown[]): string {
+  for (const input of inputs) {
+    const text = String(input || "").trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+/**
+ * QQ 渠道 Bot 信息探测器。
+ */
+export class QqBotInfoProvider implements ChatChannelBotInfoProvider {
+  readonly channel = "qq" as const;
+
+  /**
+   * 探测 QQ bot 信息。
+   */
+  async resolve(credentials: ChatBotInfoCredentialInput): Promise<ChatBotInfoResult> {
+    const appId = String(credentials.appId || "").trim();
+    const appSecret = String(credentials.appSecret || "").trim();
+    const sandbox = credentials.sandbox === true;
+
+    if (!appId || !appSecret) {
+      throw new Error("Missing appId/appSecret");
+    }
+
+    const authResponse = await fetch("https://bots.qq.com/app/getAppAccessToken", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        appId,
+        clientSecret: appSecret,
+      }),
+    });
+    const authRaw = await authResponse.text();
+    let authPayload: {
+      access_token?: string;
+      code?: number;
+      message?: string;
+    } = {};
+    try {
+      authPayload = JSON.parse(authRaw) as typeof authPayload;
+    } catch {
+      authPayload = {};
+    }
+
+    if (
+      !authResponse.ok ||
+      (typeof authPayload.code === "number" && authPayload.code !== 0) ||
+      !authPayload.access_token
+    ) {
+      const details = pickFirstNonEmpty([
+        authPayload.message,
+        authRaw,
+        `HTTP ${authResponse.status}`,
+      ]);
+      throw new Error(`QQ bot info probe failed: ${details}`);
+    }
+
+    const authHeader = `QQBot ${authPayload.access_token}`;
+    const apiBase = sandbox
+      ? "https://sandbox.api.sgroup.qq.com"
+      : "https://api.sgroup.qq.com";
+
+    const gatewayResponse = await fetch(`${apiBase}/gateway`, {
+      method: "GET",
+      headers: {
+        Authorization: authHeader,
+      },
+    });
+    const gatewayRaw = await gatewayResponse.text();
+    if (!gatewayResponse.ok) {
+      throw new Error(`QQ bot info probe failed: ${gatewayRaw || `HTTP ${gatewayResponse.status}`}`);
+    }
+
+    let botName = "";
+    let botUserId = "";
+    try {
+      const meResponse = await fetch(`${apiBase}/users/@me`, {
+        method: "GET",
+        headers: {
+          Authorization: authHeader,
+        },
+      });
+      const meRaw = await meResponse.text();
+      const mePayload = JSON.parse(meRaw) as {
+        id?: string;
+        user_id?: string;
+        username?: string;
+        nickname?: string;
+        name?: string;
+      };
+      if (meResponse.ok) {
+        botUserId = pickFirstNonEmpty([mePayload.id, mePayload.user_id]);
+        botName = pickFirstNonEmpty([
+          mePayload.username,
+          mePayload.nickname,
+          mePayload.name,
+        ]);
+      }
+    } catch {
+      // ignore profile lookup error
+    }
+
+    const name = pickFirstNonEmpty([
+      botName,
+      `QQ Bot ${appId.slice(-6)}`,
+      "QQ Bot",
+    ]);
+    const identity = pickFirstNonEmpty([botUserId, appId]);
+
+    return {
+      channel: this.channel,
+      name,
+      identity: identity || undefined,
+      botUserId: botUserId || undefined,
+      idSeed: pickFirstNonEmpty([botUserId, appId, "bot"]),
+      message: botName
+        ? "QQ bot profile fetched"
+        : "QQ credentials verified; fallback profile generated",
+    };
+  }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * QQ 渠道配置描述。
+ *
+ * 关键点（中文）
+ * - ship 层只保留 `enabled` 与 `channelAccountId`。
+ * - QQ 专属参数（sandbox 等）在 channel account 中维护。
+ */
+
+import { ChatChannelConfiguration } from "@/plugin/builtins/chat/channels/Configuration.js";
+import type { ChatChannelConfigurationDescriptor } from "@/plugin/builtins/chat/types/ChannelConfiguration.js";
+
+/**
+ * QQ 渠道配置描述器。
+ */
+export class QqChannelConfiguration extends ChatChannelConfiguration {
+  readonly channel = "qq" as const;
+
+  describe(): ChatChannelConfigurationDescriptor {
+    return {
+      channel: this.channel,
+      title: "QQ Channel Configuration",
+      description:
+        "Bind a QQ channel account and control runtime enable/disable state.",
+      version: "1.0.0",
+      capabilities: {
+        canToggleEnabled: true,
+        canBindChannelAccount: true,
+        canConfigure: true,
+      },
+      fields: {
+        ship: [
+          {
+            key: "enabled",
+            label: "Enabled",
+            description: "Whether qq channel should be started by runtime.",
+            type: "boolean",
+            source: "ship_json",
+            required: false,
+            nullable: false,
+            writable: true,
+            restartRequired: true,
+            defaultValue: false,
+            example: true,
+          },
+          {
+            key: "channelAccountId",
+            label: "Channel Account ID",
+            description:
+              "Bind channel to a channel account row in ~/.downcity/downcity.db channel_accounts.",
+            type: "string",
+            source: "ship_json",
+            required: false,
+            nullable: true,
+            writable: true,
+            restartRequired: true,
+            example: "qq-main",
+          },
+        ],
+        channelAccount: [],
+        envFallback: [],
+      },
+    };
+  }
+}

package/src/plugin/builtins/chat/channels/qq/PROMPT.direct.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动生成文件，请勿手改。
+ * 源文件：由同路径 `*.ts.txt` 生成。
+ */
+
+// Source: src/plugin/builtins/chat/channels/qq/PROMPT.direct.ts.txt
+const TEXT_MODULE_CONTENT = "# QQ Adapter 使用说明（direct 模式）\n\n## 能力范围\n- 负责 QQ 官方机器人网关（WebSocket）消息接入与发送。\n- 入站消息会由 chat service 映射到内部 `sessionId`（随机分配并持久化）。\n\n## 使用约束\n- 在 direct 模式下，你输出的 assistant 文本会自动发送到当前 QQ 会话。\n- QQ 出站回复依赖入站消息上下文（如 `chatType` 与 `messageId`）；跨会话发送请使用 `city chat send --chat-key ...`，不要在 direct metadata 中写 `chatKey`。\n- 群聊消息默认全量接入，不需要 `@` 触发。\n- 适配器会过滤机器人自回环消息并做入站去重，避免“自己回复自己”的循环。\n";
+
+export default TEXT_MODULE_CONTENT;

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

@@ -0,0 +1,398 @@
+/**
+ * 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

@@ -0,0 +1,88 @@
+/**
+ * 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";
+}