@zhin.js/adapter-qq 5.0.2 → 6.0.0

package/src/outbound-markdown.ts

@@ -1,212 +0,0 @@
-/**
- * 将 AI 出站纯文本段合并为 QQ Markdown 消息（msg_type=2）。
- * 图文混排时合并为单条 Markdown（图片语法见 QQ 官方文档）。
- */
-import { segment, type MessageElement, type MessageSegment, type SendContent } from "zhin.js";
-import { resolveMediaFile } from "./outbound-media.js";
-
-function isMessageSegment(seg: MessageElement): seg is MessageSegment {
-  return typeof seg.type === "string";
-}
-
-export type OutboundMarkdownMode = boolean | "auto";
-
-const BLOCKING_RICH_TYPES = new Set([
-  "audio",
-  "video",
-  "file",
-  "markdown",
-  "ark",
-  "embed",
-  "keyboard",
-  "button",
-  "face",
-]);
-
-const TEXT_IMAGE_MIX_TYPES = new Set(["text", "at", "image"]);
-
-function textSegment(text: string): MessageSegment {
-  return { type: "text", data: { text } };
-}
-
-export function asOutboundSegments(content: SendContent): MessageSegment[] {
-  if (typeof content === "string") return [textSegment(content)];
-  if (!Array.isArray(content)) {
-    return isMessageSegment(content) ? [content] : [];
-  }
-  return content.flatMap((item) =>
-    typeof item === "string" ? [textSegment(item)] : isMessageSegment(item) ? [item] : [],
-  );
-}
-
-export function splitReplyPrefix(segments: MessageSegment[]): {
-  prefix: MessageSegment[];
-  body: MessageSegment[];
-} {
-  const prefix: MessageSegment[] = [];
-  let i = 0;
-  while (i < segments.length && segments[i].type === "reply") {
-    prefix.push(segments[i]);
-    i++;
-  }
-  return { prefix, body: segments.slice(i) };
-}
-
-function textFromSegment(seg: MessageSegment): string {
-  if (seg.type !== "text") return "";
-  return seg.data.text ?? seg.data.content ?? "";
-}
-
-function isRemoteUrl(value: string): boolean {
-  return /^https?:\/\//i.test(value);
-}
-
-function isInlineMedia(value: string): boolean {
-  return value.startsWith("base64://")
-    || /^data:[^/]+\/[^;]+;base64,/i.test(value)
-    || value.startsWith("file://")
-    || (value.startsWith("/") && !isRemoteUrl(value));
-}
-
-/** QQ Markdown 图片语法：![说明 #宽 #高](公网 URL) */
-export function formatQqMarkdownImage(
-  url: string,
-  data: Record<string, unknown> = {},
-): string {
-  const width = typeof data.width === "number" && data.width > 0 ? data.width : 200;
-  const height = typeof data.height === "number" && data.height > 0 ? data.height : width;
-  const label = typeof data.name === "string" && data.name.trim() ? data.name.trim() : "图片";
-  return `![${label} #${width}px #${height}px](${url})`;
-}
-
-/** 将 image 段解析为 Markdown 可嵌入的 URL（https 或 data URI） */
-export function resolveImageMarkdownUrl(data: Record<string, unknown>): string | null {
-  const url = typeof data.url === "string" ? data.url : undefined;
-  const file = resolveMediaFile(data);
-
-  if (url && isRemoteUrl(url)) return url;
-  if (file && isRemoteUrl(file)) return file;
-
-  const inline = file ?? (url && isInlineMedia(url) ? url : undefined);
-  if (!inline) return null;
-
-  if (inline.startsWith("base64://")) {
-    return `data:image/png;base64,${inline.slice(9)}`;
-  }
-  if (/^data:[^/]+\/[^;]+;base64,/i.test(inline)) {
-    return inline;
-  }
-  return null;
-}
-
-export function isTextImageMixedBody(body: MessageSegment[]): boolean {
-  if (body.length === 0) return false;
-  if (body.some((seg) => !TEXT_IMAGE_MIX_TYPES.has(seg.type))) return false;
-  const hasImage = body.some((seg) => seg.type === "image");
-  const hasText = body.some((seg) => seg.type === "text" || seg.type === "at");
-  return hasImage && hasText;
-}
-
-/** 图文混排且含 base64/本地图（无法直接嵌入 Markdown 公网 URL） */
-export function isTextImageMixedWithInlineMedia(body: MessageSegment[]): boolean {
-  if (!isTextImageMixedBody(body)) return false;
-  return body.some((seg) => {
-    if (seg.type !== "image") return false;
-    const url = typeof seg.data.url === "string" ? seg.data.url : undefined;
-    const file = resolveMediaFile(seg.data);
-    if (url && isRemoteUrl(url)) return false;
-    if (file && isRemoteUrl(file)) return false;
-    return Boolean(resolveMediaFile(seg.data) || (url && isInlineMedia(url)));
-  });
-}
-
-function segmentToMarkdownPart(seg: MessageSegment): string {
-  if (seg.type === "text") return textFromSegment(seg);
-  if (seg.type === "at") return `<@${String(seg.data.user_id ?? "")}>`;
-  if (seg.type === "image") {
-    const src = resolveImageMarkdownUrl(seg.data);
-    return src ? formatQqMarkdownImage(src, seg.data) : "";
-  }
-  return "";
-}
-
-function shouldConvertTextOnly(mode: OutboundMarkdownMode | undefined, bodyText: string): boolean {
-  if (mode === false) return false;
-  if (mode === true) return bodyText.trim().length > 0;
-  return hasMarkdownHint(bodyText);
-}
-
-function hasMarkdownHint(text: string): boolean {
-  if (text.includes('**') || text.includes('__') || text.includes('`')) return true;
-  if (text.includes('](') || text.includes('|')) return true;
-  return text.split('\n').some((line) => {
-    const trimmed = line.trimStart();
-    return trimmed.startsWith('# ') || trimmed.startsWith('## ')
-      || trimmed.startsWith('> ')
-      || trimmed.startsWith('- ')
-      || trimmed.startsWith('* ')
-      || trimmed.startsWith('+ ');
-  });
-}
-
-function mergeTextImageToMarkdown(
-  prefix: MessageSegment[],
-  body: MessageSegment[],
-): SendContent | null {
-  if (body.some((seg) => seg.type === "image" && !resolveImageMarkdownUrl(seg.data))) {
-    return null;
-  }
-  const merged = body.map(segmentToMarkdownPart).join("");
-  if (!merged.trim()) return null;
-  return [...prefix, segment("markdown", { content: merged })];
-}
-
-/**
- * 出站归一化：保留 leading `reply`，将连续 text 或 text+image 合并为单条 markdown 段。
- * 含内联 base64 图的图文混排须走 outbound-mixed-media（msg_type=7），此处不处理。
- */
-export function normalizeOutboundMarkdown(
-  content: SendContent,
-  mode: OutboundMarkdownMode | undefined = "auto",
-): SendContent {
-  const segments = asOutboundSegments(content);
-  if (segments.length === 0) return content;
-
-  const { prefix, body } = splitReplyPrefix(segments);
-  if (body.length === 0) return content;
-  if (mode === false) return content;
-
-  if (body.some((seg) => BLOCKING_RICH_TYPES.has(seg.type))) {
-    return content;
-  }
-
-  if (body.some((seg) => seg.type === "markdown")) {
-    return content;
-  }
-
-  if (isTextImageMixedBody(body)) {
-    if (isTextImageMixedWithInlineMedia(body)) {
-      return content;
-    }
-    const mixed = mergeTextImageToMarkdown(prefix, body);
-    return mixed ?? content;
-  }
-
-  if (body.some((seg) => seg.type === "image")) {
-    return content;
-  }
-
-  if (body.some((seg) => seg.type !== "text" && seg.type !== "at")) {
-    return content;
-  }
-
-  const merged = body
-    .map((seg) => (seg.type === "at"
-      ? `<@${String(seg.data.user_id ?? "")}>`
-      : textFromSegment(seg)))
-    .join("");
-
-  if (!shouldConvertTextOnly(mode, merged)) return content;
-
-  return [...prefix, segment("markdown", { content: merged })];
-}

package/src/outbound-media.ts

@@ -1,58 +0,0 @@
-/**
- * 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);
-}
-
-/** 解析 image/audio/video/file 段的本地或内联 payload（供 mixed-media 上传复用） */
-export 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/outbound-mixed-media.ts

@@ -1,101 +0,0 @@
-/**
- * QQ 群/私聊图文混排（msg_type=7）。
- * 内联 base64 图无法作为 Markdown 公网 URL，须先上传 file_info 再与文本同条发送。
- */
-import { randomInt } from "node:crypto";
-import type { MessageSegment, SendContent } from "zhin.js";
-import {
-  asOutboundSegments,
-  isTextImageMixedWithInlineMedia,
-  splitReplyPrefix,
-} from "./outbound-markdown.js";
-import { resolveMediaFile } from "./outbound-media.js";
-
-function textFromSegment(seg: MessageSegment): string {
-  if (seg.type !== "text") return "";
-  return seg.data.text ?? seg.data.content ?? "";
-}
-
-function isRemoteUrl(value: string): boolean {
-  return /^https?:\/\//i.test(value);
-}
-
-function extractInlineFileData(source: string): string {
-  if (source.startsWith("base64://")) return source.slice(9);
-  if (/^data:[^/]+\/[^;]+;base64,/i.test(source)) {
-    return source.replace(/^data:[^/]+\/[^;]+;base64,/i, "");
-  }
-  return source;
-}
-
-export function buildQqImageUploadPayload(
-  imageSeg: MessageSegment,
-): { file_type: 1; url?: string; file_data?: string } {
-  const data = imageSeg.data;
-  const url = typeof data.url === "string" ? data.url : undefined;
-  const file = resolveMediaFile(data);
-  const remote = [url, file].find((item) => item && isRemoteUrl(item));
-  if (remote) {
-    return { file_type: 1, url: remote };
-  }
-  const inline = file ?? url;
-  if (!inline) {
-    throw new Error("QQ 图文混排：图片段缺少 url/file/base64");
-  }
-  return { file_type: 1, file_data: extractInlineFileData(inline) };
-}
-
-export function buildTextImageMixedBodyText(body: MessageSegment[]): string {
-  return body
-    .map((seg) => {
-      if (seg.type === "text") return textFromSegment(seg);
-      if (seg.type === "at") return `<@${String(seg.data.user_id ?? "")}>`;
-      return "";
-    })
-    .join("");
-}
-
-export function firstImageSegment(body: MessageSegment[]): MessageSegment | undefined {
-  return body.find((seg) => seg.type === "image");
-}
-
-export function shouldSendTextImageMixedMedia(
-  content: SendContent,
-  mode: boolean | "auto" | undefined,
-): boolean {
-  if (mode === false) return false;
-  const { body } = splitReplyPrefix(asOutboundSegments(content));
-  return isTextImageMixedWithInlineMedia(body);
-}
-
-export interface QqMixedMediaMessagePayload {
-  msg_type: 7;
-  content: string;
-  media: { file_info: string };
-  msg_seq: number;
-  msg_id?: string;
-  event_id?: string;
-}
-
-export function buildMixedMediaMessagePayload(
-  content: SendContent,
-  fileInfo: string,
-): QqMixedMediaMessagePayload {
-  const segments = asOutboundSegments(content);
-  const { prefix, body } = splitReplyPrefix(segments);
-  const payload: QqMixedMediaMessagePayload = {
-    msg_type: 7,
-    content: buildTextImageMixedBodyText(body),
-    media: { file_info: fileInfo },
-    msg_seq: randomInt(1, 1_000_000),
-  };
-  const reply = prefix[prefix.length - 1];
-  if (reply?.type === "reply") {
-    if (typeof reply.data.event_id === "string") {
-      payload.event_id = reply.data.event_id;
-    } else if (reply.data.id != null) {
-      payload.msg_id = String(reply.data.id);
-    }
-  }
-  return payload;
-}

package/src/qq-endpoint-manager.ts

@@ -1,199 +0,0 @@
-import type {
-  EndpointConfigRecord,
-  EndpointManager,
-  ProvisionContext,
-} from 'zhin.js';
-import type { QQAdapter } from './adapter.js';
-import { ReceiverMode as QQReceiverMode, type QQEndpointConfig, type ReceiverMode } from './types.js';
-
-import { startQqBindFlow } from './qq-bind-flow.js';
-import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
-
-const DEFAULT_INTENTS = [
-  'GUILDS',
-  'GUILD_MEMBERS',
-  'GUILD_MESSAGE_REACTIONS',
-  'DIRECT_MESSAGE',
-  'GROUP_AND_C2C_EVENT',
-  'INTERACTION',
-  'MESSAGE_AUDIT',
-  'AUDIO_ACTION',
-  'PUBLIC_GUILD_MESSAGES',
-] as const;
-
-function clonePlainConfig<T>(value: T): T {
-  return JSON.parse(JSON.stringify(value)) as T;
-}
-
-function resolveQqEndpointTemplate(root: ProvisionContext['root']): Partial<QQEndpointConfig<ReceiverMode>> {
-  const configService = root.inject('config') as {
-    getRaw?: (f: string) => { endpoints?: Array<Record<string, unknown>> };
-    primaryFile?: string;
-  } | undefined;
-  const raw = configService?.primaryFile && configService.getRaw
-    ? configService.getRaw(configService.primaryFile)
-    : undefined;
-  const existing = raw?.endpoints?.find((e) => e.context === 'qq');
-  if (!existing) {
-    return {
-      mode: QQReceiverMode.WEBSOCKET,
-      sandbox: false,
-      timeout: 10_000,
-      data_dir: './data',
-      intents: [...DEFAULT_INTENTS],
-    };
-  }
-  const { name: _n, appid: _a, secret: _s, context: _c, ...rest } = existing;
-  return clonePlainConfig(rest) as Partial<QQEndpointConfig<ReceiverMode>>;
-}
-
-function resolveBindOperatorId(
-  userOpenId: string | undefined,
-  ctx: ProvisionContext,
-): string {
-  const fromApi = userOpenId?.trim();
-  if (fromApi) return fromApi;
-  return ctx.message.$sender?.id?.trim() ?? '';
-}
-
-function applyBindOwnership(
-  template: Partial<QQEndpointConfig<ReceiverMode>>,
-  operatorId: string,
-): Partial<QQEndpointConfig<ReceiverMode>> {
-  const { master: _m, aiAccess, ...rest } = template as Record<string, unknown>;
-  if (!operatorId) {
-    return rest as Partial<QQEndpointConfig<ReceiverMode>>;
-  }
-  const prior = aiAccess as {
-    mode?: string;
-    groups?: string[];
-    denyMessage?: string;
-  } | undefined;
-  return {
-    ...rest,
-    master: operatorId,
-    aiAccess: {
-      mode: prior?.mode ?? 'whitelist',
-      users: [operatorId],
-      groups: Array.isArray(prior?.groups) ? [...prior.groups] : [],
-      denyMessage:
-        typeof prior?.denyMessage === 'string'
-          ? prior.denyMessage
-          : '当前用户尚未开放 AI 功能，请联系开启。',
-    },
-  } as Partial<QQEndpointConfig<ReceiverMode>>;
-}
-
-function readQqConfigs(root: ProvisionContext['root']): EndpointConfigRecord[] {
-  const configService = root.inject('config') as { getRaw?: (f: string) => { endpoints?: EndpointConfigRecord[] } ; primaryFile?: string } | undefined;
-  if (!configService?.primaryFile || !configService.getRaw) return [];
-  const raw = configService.getRaw(configService.primaryFile);
-  return (raw?.endpoints ?? []).filter((e) => e.context === 'qq');
-}
-
-/** 全局单例：同一时间只允许一个 QQ 扫码绑定 */
-let activeStopFlow: (() => void) | null = null;
-
-export class QqEndpointManager implements EndpointManager {
-  constructor(private readonly adapter: QQAdapter) {}
-
-  supportsProvision(): boolean {
-    return true;
-  }
-
-  listEndpoints(): EndpointConfigRecord[] {
-    return readQqConfigs(this.adapter.plugin.root);
-  }
-
-  cancelProvision(): boolean {
-    if (!activeStopFlow) return false;
-    activeStopFlow();
-    activeStopFlow = null;
-    return true;
-  }
-
-  async addEndpoint(ctx: ProvisionContext): Promise<EndpointConfigRecord> {
-    if (activeStopFlow) {
-      throw new Error('已有进行中的 QQ 机器人绑定，请先 /endpoint cancel');
-    }
-
-    let endpointName: string | undefined;
-    const nameMatch = ctx.message.$raw?.match(/\/endpoint\s+add\s+qq\s+(\S+)/);
-    if (nameMatch?.[1]) {
-      endpointName = nameMatch[1];
-    }
-
-    return new Promise<EndpointConfigRecord>((resolve, reject) => {
-      const stopFlow = startQqBindFlow(
-        {
-          onQrDisplayed: async (url) => {
-            await ctx.onStatusUpdate('请用手机 QQ 扫描二维码完成机器人绑定。', {
-              qrcode: url,
-            });
-          },
-          onQrExpired: async () => {
-            await ctx.onStatusUpdate('二维码已过期，正在刷新，请扫描新二维码…');
-          },
-          onSuccess: async (credentials) => {
-            activeStopFlow = null;
-            const [{ appId, appSecret, userOpenId }] = credentials;
-            const name = endpointName?.trim() || appId;
-            await ctx.onStatusUpdate(
-              '凭据绑定成功，正在写入配置…',
-            );
-            const envKeys = persistQqCredentialsToEnv(name, appId, appSecret);
-            const template = resolveQqEndpointTemplate(ctx.root);
-            const operatorId = resolveBindOperatorId(userOpenId, ctx);
-            const owned = applyBindOwnership(template, operatorId);
-            resolve({
-              context: 'qq',
-              name,
-              appid: envKeys.appidRef,
-              secret: envKeys.secretRef,
-              ...owned,
-            } as EndpointConfigRecord);
-          },
-          onFailure: async (error) => {
-            activeStopFlow = null;
-            reject(error);
-          },
-        },
-        { source: 'zhin' },
-      );
-      activeStopFlow = stopFlow;
-    });
-  }
-
-  async editEndpoint(name: string, ctx: ProvisionContext): Promise<EndpointConfigRecord> {
-    const existing = this.listEndpoints().find((e) => e.name === name);
-    if (!existing) {
-      throw new Error(`配置中不存在 qq/${name}`);
-    }
-    await ctx.onStatusUpdate(
-      `QQ 官方机器人暂不支持在线改凭据，请 /endpoint remove qq ${name} 后重新 /endpoint add qq。`,
-    );
-    return existing;
-  }
-
-  async removeEndpoint(name: string): Promise<boolean> {
-    return this.listEndpoints().some((e) => e.name === name);
-  }
-
-  async startEndpoint(name: string, ctx: ProvisionContext): Promise<void> {
-    if (!this.listEndpoints().some((e) => e.name === name)) {
-      throw new Error(`配置中不存在 qq/${name}`);
-    }
-    await ctx.onStatusUpdate(`正在连接 qq/${name}…`);
-  }
-
-  async stopEndpoint(name: string): Promise<boolean> {
-    return this.adapter.endpoints.has(name);
-  }
-}
-
-export function disposeQqEndpointProvision(): void {
-  if (activeStopFlow) {
-    activeStopFlow();
-    activeStopFlow = null;
-  }
-}

package/src/sdk-version.ts

@@ -1,21 +0,0 @@
-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-endpoint.
- * 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/segment-mapper.ts

@@ -1 +0,0 @@
-export { toCanonicalSegments, fromCanonicalSegments } from 'zhin.js';

package/src/types.ts

@@ -1,52 +0,0 @@
-/**
- * QQ 官方机器人适配器类型定义
- */
-import { type Bot as QQOfficialBot, type ReceiverMode, type ApplicationPlatform } from 'qq-official-bot';
-
-export { ReceiverMode } from "qq-official-bot";
-export type { ApplicationPlatform, Intent } from "qq-official-bot";
-
-export type QQEndpointConfig<
-  T extends ReceiverMode,
-  M extends ApplicationPlatform = ApplicationPlatform,
-> = QQOfficialBot.Config<T, M> & {
-  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";
-  /** 本 Endpoint AI 访问控制（见 docs/advanced/content-moderation.md） */
-  aiAccess?: {
-    mode?: 'open' | 'closed' | 'whitelist';
-    users?: string[];
-    groups?: string[];
-    denyMessage?: string;
-  };
-};
-
-export interface QQEndpoint<
-  T extends ReceiverMode,
-  M extends ApplicationPlatform = ApplicationPlatform,
-> {
-  $config: QQEndpointConfig<T, M>;
-}