@downcity/plugins 1.0.4

package/src/chat/channels/feishu/types/FeishuChannel.ts

@@ -0,0 +1,131 @@
+/**
+ * Feishu 渠道共享类型。
+ *
+ * 关键点（中文）
+ * - 集中声明 Feishu 渠道的配置、事件、消息体与上传下载中间结构。
+ * - `plugins/chat/channels/feishu/*` 统一依赖这里，避免实现文件内联大量局部类型。
+ */
+
+/**
+ * 飞书适配器配置。
+ */
+export interface FeishuConfig {
+  /**
+   * 飞书应用 AppId。
+   */
+  appId: string;
+  /**
+   * 飞书应用 AppSecret。
+   */
+  appSecret: string;
+  /**
+   * 是否启用飞书渠道。
+   */
+  enabled: boolean;
+  /**
+   * 可选的飞书 Open API 域名。
+   */
+  domain?: string;
+}
+
+/**
+ * 飞书消息事件。
+ */
+export interface FeishuMessageEvent {
+  /**
+   * 发送者信息。
+   */
+  sender?: {
+    /**
+     * 发送者 ID 集合。
+     */
+    sender_id?: {
+      /**
+       * 用户 user_id。
+       */
+      user_id?: string;
+      /**
+       * 用户 open_id。
+       */
+      open_id?: string;
+      /**
+       * 用户 union_id。
+       */
+      union_id?: string;
+      /**
+       * 兼容 chat_id 字段。
+       */
+      chat_id?: string;
+    };
+  };
+  /**
+   * 消息主体。
+   */
+  message?: {
+    /**
+     * 会话 chat_id。
+     */
+    chat_id: string;
+    /**
+     * 原始内容 JSON。
+     */
+    content: string;
+    /**
+     * 消息类型。
+     */
+    message_type: string;
+    /**
+     * 会话类型。
+     */
+    chat_type: string;
+    /**
+     * 消息 ID。
+     */
+    message_id: string;
+    /**
+     * 根消息 ID。
+     */
+    root_id?: string;
+    /**
+     * 父消息 ID。
+     */
+    parent_id?: string;
+  };
+}
+
+/**
+ * 飞书消息发送类型。
+ */
+export type FeishuMessagePayloadType = "text" | "file" | "image" | "post";
+
+/**
+ * 飞书发送者归一化结果。
+ */
+export interface FeishuSenderIdentity {
+  /**
+   * 归一化后的发送者 ID。
+   */
+  senderId?: string;
+  /**
+   * 发送者 ID 的类型。
+   */
+  idType?: "open_id" | "user_id" | "union_id";
+}
+
+/**
+ * 飞书下载后的本地附件结构。
+ */
+export interface FeishuDownloadedAttachment {
+  /**
+   * 统一附件类型。
+   */
+  type: "document" | "photo" | "voice" | "audio" | "video";
+  /**
+   * 本地绝对路径。
+   */
+  path: string;
+  /**
+   * 可选说明文本。
+   */
+  desc?: string;
+}

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

@@ -0,0 +1,137 @@
+/**
+ * QQ Bot 信息探测实现。
+ *
+ * 关键点（中文）
+ * - 先校验 appId/appSecret 可换取 access token。
+ * - 再验证 gateway 可达，并尝试读取 `users/@me`。
+ */
+
+import type {
+  ChatBotInfoCredentialInput,
+  ChatBotInfoResult,
+  ChatChannelBotInfoProvider,
+} from "@/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/chat/channels/qq/Configuration.ts

@@ -0,0 +1,64 @@
+/**
+ * QQ 渠道配置描述。
+ *
+ * 关键点（中文）
+ * - ship 层只保留 `enabled` 与 `channelAccountId`。
+ * - QQ 专属参数（sandbox 等）在 channel account 中维护。
+ */
+
+import { ChatChannelConfiguration } from "@/chat/channels/Configuration.js";
+import type { ChatChannelConfigurationDescriptor } from "@/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/chat/channels/qq/PROMPT.direct.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动生成文件，请勿手改。
+ * 源文件：由同路径 `*.ts.txt` 生成。
+ */
+
+// Source: src/chat/channels/qq/PROMPT.direct.ts.txt
+const TEXT_MODULE_CONTENT = "# QQ Adapter 使用说明（direct 模式）\n\n## 能力范围\n- 负责 QQ 官方机器人网关（WebSocket）消息接入与发送。\n- 入站消息会由 chat plugin runtime 映射到内部 `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/chat/channels/qq/PROMPT.direct.ts.txt

@@ -0,0 +1,11 @@
+# QQ Adapter 使用说明（direct 模式）
+
+## 能力范围
+- 负责 QQ 官方机器人网关（WebSocket）消息接入与发送。
+- 入站消息会由 chat plugin runtime 映射到内部 `sessionId`（随机分配并持久化）。
+
+## 使用约束
+- 在 direct 模式下，你输出的 assistant 文本会自动发送到当前 QQ 会话。
+- QQ 出站回复依赖入站消息上下文（如 `chatType` 与 `messageId`）；跨会话发送请使用 `city chat send --chat-key ...`，不要在 direct metadata 中写 `chatKey`。
+- 群聊消息默认全量接入，不需要 `@` 触发。
+- 适配器会过滤机器人自回环消息并做入站去重，避免“自己回复自己”的循环。