@zhin.js/adapter-qq 2.0.11 → 3.0.0

package/src/outbound-media.ts

@@ -0,0 +1,57 @@
+/**
+ * QQ 官方出站媒体归一化。
+ * qq-official-bot 的 formatMediaData 对 data.url 直接当远程 URL 上传；
+ * base64:// / data:...;base64 须走 data.file 才会解析为 file_data。
+ */
+import type { MessageElement, MessageSegment, SendContent } from "zhin.js";
+
+const MEDIA_TYPES = new Set(["image", "audio", "video", "file"]);
+
+function isMessageSegment(seg: MessageElement): seg is MessageSegment {
+  return typeof seg.type === "string";
+}
+
+function isRemoteUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function isInlineBase64(value: string): boolean {
+  return value.startsWith("base64://") || /^data:[^/]+\/[^;]+;base64,/i.test(value);
+}
+
+function resolveMediaFile(data: Record<string, unknown>): string | undefined {
+  const url = typeof data.url === "string" ? data.url : undefined;
+  const file = typeof data.file === "string" ? data.file : undefined;
+  const base64 = typeof data.base64 === "string" ? data.base64 : undefined;
+
+  if (file && !isRemoteUrl(file)) return file;
+  if (url && isInlineBase64(url)) return url;
+  if (url && !isRemoteUrl(url) && (url.startsWith("file://") || url.startsWith("/"))) return url;
+  if (base64) return base64.startsWith("base64://") ? base64 : `base64://${base64}`;
+  return undefined;
+}
+
+function normalizeMediaSegment(seg: MessageSegment): MessageSegment {
+  if (!MEDIA_TYPES.has(seg.type)) return seg;
+
+  const data = { ...seg.data } as Record<string, unknown>;
+  const file = resolveMediaFile(data);
+  if (!file) return seg;
+
+  delete data.url;
+  delete data.base64;
+  data.file = file;
+  return { type: seg.type, data } as MessageSegment;
+}
+
+/** 将 Zhin 出站 image/base64 段转为 qq-official-bot 可识别的 file 字段 */
+export function normalizeOutboundMedia(content: SendContent): SendContent {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) {
+    return isMessageSegment(content) ? normalizeMediaSegment(content) : content;
+  }
+  return content.map((item) => {
+    if (typeof item === "string") return item;
+    return isMessageSegment(item) ? normalizeMediaSegment(item) : item;
+  });
+}

package/src/sdk-version.ts

@@ -0,0 +1,21 @@
+import { createRequire } from "node:module";
+import adapterPkg from "../package.json" with { type: "json" };
+
+const require = createRequire(import.meta.url);
+
+function readDepVersion(dep: string): string {
+  try {
+    return (require(`${dep}/package.json`) as { version: string }).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/** HTTP header name for outbound QQ API requests. */
+export const SDK_VERSION_HEADER = "x-sdk-version";
+
+/**
+ * Composite SDK identity: Zhin adapter + underlying qq-official-bot.
+ * Example: `zhin-adapter-qq/v2.0.11+qq-official-bot/v1.2.1`
+ */
+export const SDK_VERSION = `zhin-adapter-qq/v${adapterPkg.version}+qq-official-bot/v${readDepVersion("qq-official-bot")}`;

package/src/types.ts

@@ -14,6 +14,28 @@ export type QQBotConfig<
   context: "qq";
   name: string;
   data_dir?: string;
+  /**
+   * middleware 模式：挂在 host-router 的回调路径（默认 `/qq/webhook`，完整 URL 为 `{host}:8086/qq/webhook`，无 `/api` 前缀）。
+   * webhook 独立端口模式：使用 qq-official-bot 的 `path` 字段。
+   */
+  webhookPath?: string;
+  /**
+   * 自定义 access token 接口（完整 URL）。
+   * 默认 `https://bots.qq.com/app/getAppAccessToken`；代理或私有部署时可覆盖。
+   */
+  accessTokenUrl?: string;
+  /**
+   * 自定义 gateway 接口（完整 URL 或相对路径，如 `/gateway/bot`）。
+   * 响应中的 `url` 为 WebSocket 地址；**仅 `mode: websocket` 入站时使用**。
+   */
+  gatewayUrl?: string;
+  /**
+   * AI 出站是否转为 QQ Markdown（`msg_type=2`）。
+   * - `auto`（默认）：正文含 Markdown 语法时转换
+   * - `true`：纯文本也走 Markdown
+   * - `false`：保持纯文本
+   */
+  outboundMarkdown?: boolean | "auto";
 };
 
 export interface QQBot<