@zhin.js/adapter-qq 1.0.84 → 1.1.0

package/src/index.ts

@@ -1,326 +1,66 @@
-/**
- * QQ 官方适配器入口：类型扩展、导出、注册
- */
-import path from "node:path";
-import { usePlugin, type Plugin, type IGroupManagement, createGroupManagementTools, type ToolFeature } from "zhin.js";
-import { QQAdapter } from "./adapter.js";
-import { PageManager } from "@zhin.js/console";
-
-declare module "zhin.js" {
-  namespace Plugin {
-    interface Contexts {
-      web: PageManager;
-    }
-  }
-}
-
-declare module "zhin.js" {
-  interface Adapters {
-    qq: QQAdapter;
-  }
-}
-
-export * from "./types.js";
-export { QQBot } from "./bot.js";
-export { QQAdapter } from "./adapter.js";
-
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-
-provide({
-  name: "qq",
-  description: "QQ Official Bot Adapter",
-  mounted: async (p: Plugin) => {
-    const adapter = new QQAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: QQAdapter) => {
-    await adapter.stop();
-  },
-});
-
-useContext('tool', 'qq', (toolService: ToolFeature, qq: QQAdapter) => {
-  const groupTools = createGroupManagementTools(
-    qq as unknown as IGroupManagement,
-    'qq',
-  );
-  const disposers: (() => void)[] = groupTools.map(t => toolService.addTool(t, plugin.name));
-
-  // 获取频道列表
-  disposers.push(toolService.addTool({
-    name: 'qq_list_guilds',
-    description: '获取 QQ 频道列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-      },
-      required: ['bot'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const bot = qq.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const guilds = await bot.getGuilds();
-      return { guilds, count: guilds.length };
-    },
-  }, plugin.name));
-
-  // 获取子频道列表
-  disposers.push(toolService.addTool({
-    name: 'qq_list_channels',
-    description: '获取 QQ 频道下的子频道列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '频道 ID' },
-      },
-      required: ['bot', 'guild_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const bot = qq.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const channels = await bot.getChannels(args.guild_id);
-      return { channels, count: channels.length };
-    },
-  }, plugin.name));
-
-  // 获取角色列表
-  disposers.push(toolService.addTool({
-    name: 'qq_list_roles',
-    description: '获取 QQ 频道角色列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '频道 ID' },
-      },
-      required: ['bot', 'guild_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const bot = qq.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const roles = await bot.getGuildRoles(args.guild_id);
-      return { roles, count: roles.length };
-    },
-  }, plugin.name));
-
-  // 创建角色
-  disposers.push(toolService.addTool({
-    name: 'qq_create_role',
-    description: '创建 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        name: { type: 'string', description: '角色名称' },
-        color: { type: 'number', description: '颜色（RGB 十进制数值）' },
-      },
-      required: ['bot', 'guild_id', 'name'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const bot = qq.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const role = await bot.createGuildRole(args.guild_id, args.name, args.color);
-      return { success: !!role, role, message: role ? `角色 "${args.name}" 创建成功` : '创建失败' };
-    },
-  }, plugin.name));
-
-  // 添加角色
-  disposers.push(toolService.addTool({
-    name: 'qq_add_role',
-    description: '给成员添加 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['bot', 'guild_id', 'channel_id', 'user_id', 'role_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const bot = qq.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.addMemberRole(args.guild_id, args.channel_id, args.user_id, args.role_id);
-      return { success, message: success ? '已给成员添加角色' : '操作失败' };
-    },
-  }, plugin.name));
-
-  // 移除角色
-  disposers.push(toolService.addTool({
-    name: 'qq_remove_role',
-    description: '移除成员的 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['bot', 'guild_id', 'channel_id', 'user_id', 'role_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const bot = qq.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.removeMemberRole(args.guild_id, args.channel_id, args.user_id, args.role_id);
-      return { success, message: success ? '已移除成员的角色' : '操作失败' };
-    },
-  }, plugin.name));
-
-  // 子频道详情
-  disposers.push(toolService.addTool({
-    name: 'qq_channel_info',
-    description: '获取 QQ 频道中指定子频道的详细信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-      },
-      required: ['bot', 'channel_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const bot = qq.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const info = await bot.getChannelInfo(args.channel_id);
-      return info;
-    },
-  }, plugin.name));
-
-  // 单成员详情
-  disposers.push(toolService.addTool({
-    name: 'qq_member_detail',
-    description: '获取 QQ 频道中指定成员的详细信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-      },
-      required: ['bot', 'guild_id', 'user_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const bot = qq.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const member = await bot.getGuildMember(args.guild_id, args.user_id);
-      return member;
-    },
-  }, plugin.name));
-
-  return () => disposers.forEach(d => d());
-});
-
-// ── Web 控制台 ─────────────────────────────────────────────────────────
-useContext("web", (pageManager) => {
-  pageManager.addEntry({
-    id: "qq",
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    meta: { name: "QQ" },
-  });
-});
-
-useContext("router", "qq", (router: any, qq: QQAdapter) => {
-  router.get("/api/qq/bots", async (ctx: any) => {
-    try {
-      const bots = Array.from(qq.bots.values());
-      const result = await Promise.all(bots.map(async (bot) => {
-        try {
-          let guildCount = 0;
-          try { const guilds = await bot.getGuilds(); guildCount = guilds?.length || 0; } catch {}
-          return {
-            name: bot.$config.name,
-            connected: bot.$connected || false,
-            guildCount,
-            status: bot.$connected ? "online" : "offline",
-          };
-        } catch {
-          return { name: bot.$config.name, connected: false, guildCount: 0, status: "error" };
-        }
-      }));
-      ctx.body = { success: true, data: result };
-    } catch {
-      ctx.status = 500;
-      ctx.body = { success: false, error: "获取机器人数据失败" };
-    }
-  });
-
-  // Bot 连接/断开
-  router.post("/api/qq/bots/:name/connect", async (ctx: any) => {
-    try {
-      const bot = qq.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (bot.$connected) { ctx.body = { success: true, message: "已经在线" }; return; }
-      await bot.$connect();
-      ctx.body = { success: true, message: "连接成功" };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "连接失败" };
-    }
-  });
-
-  router.post("/api/qq/bots/:name/disconnect", async (ctx: any) => {
-    try {
-      const bot = qq.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (!bot.$connected) { ctx.body = { success: true, message: "已经离线" }; return; }
-      await bot.$disconnect();
-      ctx.body = { success: true, message: "已断开" };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "断开失败" };
-    }
-  });
-
-  // 频道列表
-  router.get("/api/qq/bots/:name/guilds", async (ctx: any) => {
-    try {
-      const bot = qq.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (!bot.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Bot 未连接" }; return; }
-      const guilds = await bot.getGuilds();
-      ctx.body = { success: true, data: guilds || [] };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "获取频道失败" };
-    }
-  });
-
-  // 子频道列表
-  router.get("/api/qq/bots/:name/guilds/:guildId/channels", async (ctx: any) => {
-    try {
-      const bot = qq.bots.get(ctx.params.name);
-      if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
-      if (!bot.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Bot 未连接" }; return; }
-      const channels = await bot.getChannels(ctx.params.guildId);
-      ctx.body = { success: true, data: channels || [] };
-    } catch (e: any) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e?.message || "获取子频道失败" };
-    }
-  });
-});
+export {
+  formatInboundContent,
+  formatOutboundText,
+  resolveOutboundMessageId,
+  resolveQqConfig,
+  senderDisplayName,
+  type QqAdapterConfig,
+  type QqChannelKind,
+  type QqInboundMessage,
+  type QqWireSegment,
+  type ResolvedQqConfig,
+  type ResolvedQqHttpConfig,
+  type ResolvedQqWebsocketConfig,
+} from './protocol.js';
+
+export {
+  DEFAULT_QQ_BOT_KIND,
+  QQ_INTENTS_BY_KIND,
+  defaultQqEndpointIntentFields,
+  parseQqBotKind,
+  resolveQqIntents,
+  type QqBotKind,
+  type QqIntent,
+} from './qq-intents.js';
+
+export {
+  formatOutbound,
+  resolveMediaFile,
+  type QqOutboundElem,
+  type QqOutboundMessage,
+} from './outbound.js';
+
+export {
+  QqHttpEndpoint,
+  QqWebsocketEndpoint,
+  type CreateQqBot,
+  type CreateQqHttpBot,
+  type QqBotTransport,
+  type QqOfficialApi,
+  type QqEndpointOptions,
+  type QqHttpBotTransport,
+  type QqHttpEndpointOptions,
+} from './endpoint.js';
+
+export {
+  registerQqWebhookRoutes,
+  handleQqWebhookRequest,
+  readRequestBodyText,
+  defaultCreateHttpBot,
+  type QqWebhookHandler,
+} from './webhook.js';
+
+export {
+  bindQqBotInboundEvents,
+  defaultCreateBot,
+  normalizeQqMessage,
+} from './ws.js';
+
+export { qqClient, type QqClientEventMap } from './client.js';
+
+export {
+  checkQqPlatformPermit,
+  normalizeQqGuildSenderForPermit,
+  platformPermit,
+  qqGuildPermitResolver,
+} from './platform-permit.js';

package/src/outbound.ts

@@ -0,0 +1,255 @@
+/**
+ * QQ 官方出站富媒体归一化：把渲染后的 payload 转为 qq-official-bot 可识别的
+ * Sendable 结构（文本串 + 消息段）。移植自 legacy 版 outbound-media /
+ * outbound-markdown / outbound-keyboard。
+ *
+ * 移植面：
+ * - image：http(s) URL 直发（data.url）；base64://、data:...;base64、本地路径
+ *   归一到 data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
+ * - markdown：data.content 原文，或 custom_template_id + params 模板。
+ * - keyboard：data.rows 按钮矩阵展开为 button 段（SDK processButtons 组装
+ *   keyboard 载荷）；按钮消息必须带 markdown，故同行文本合并为 markdown 段。
+ *   data.id 模板键盘原样透传。
+ * 不可映射的段一律降级为文本并 warn（保持既有 fallback 行为）。
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { isMediaRef } from '@zhin.js/core';
+import type { QqWireSegment } from './protocol.js';
+
+const logger = getLogger('qq');
+
+/** qq-official-bot Sendable 的最小结构子集（字符串模板或消息段）。 */
+export interface QqOutboundElem {
+  readonly type: string;
+  readonly data: Record<string, unknown>;
+}
+
+export type QqOutboundMessage = string | QqOutboundElem | readonly (string | QqOutboundElem)[];
+
+interface QqOutboundButtonSpec {
+  readonly id?: string;
+  readonly label?: string;
+  readonly payload?: string;
+  readonly disabled?: boolean;
+  readonly style?: 'primary' | 'danger' | 'secondary';
+  readonly mode?: string;
+  readonly command?: { readonly enter?: boolean; readonly reply?: boolean };
+}
+
+/**
+ * 解析 image/audio/video/file 段的投递源（canonical MediaRef 唯一来源）：
+ * - kind=url → data.url 直发；
+ * - kind=base64 / path / file → data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
+ */
+export function resolveMediaFile(data: Record<string, unknown>): string | undefined {
+  const media = data.media;
+  if (!isMediaRef(media)) return undefined;
+  if (media.kind === 'url') return undefined;
+  if (media.kind === 'base64') {
+    return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+  }
+  return media.value;
+}
+
+function normalizeMediaSegment(seg: QqWireSegment): QqOutboundElem | null {
+  const media = (seg.data ?? {}).media;
+  if (!isMediaRef(media)) {
+    // 无 canonical 媒体引用：无法投递，降级留痕
+    logger.warn(formatCompact({
+      op: 'qq_outbound_media_dropped',
+      type: seg.type,
+      reason: 'missing_media_ref',
+    }));
+    return null;
+  }
+  if (media.kind === 'url') {
+    return { type: seg.type, data: { url: media.value } };
+  }
+  const file = resolveMediaFile(seg.data ?? {});
+  if (!file) {
+    logger.warn(formatCompact({
+      op: 'qq_outbound_media_dropped',
+      type: seg.type,
+      reason: 'missing_source',
+    }));
+    return null;
+  }
+  return { type: seg.type, data: { file } };
+}
+
+function normalizeMarkdownSegment(seg: QqWireSegment): QqOutboundElem | null {
+  const data = seg.data ?? {};
+  const templateId = typeof data.custom_template_id === 'string' && data.custom_template_id
+    ? data.custom_template_id
+    : typeof data.template_id === 'string' && data.template_id
+      ? data.template_id
+      : undefined;
+  if (templateId) {
+    return {
+      type: 'markdown',
+      data: {
+        custom_template_id: templateId,
+        params: Array.isArray(data.params) ? data.params : [],
+      },
+    };
+  }
+  const content = String(data.content ?? data.text ?? '');
+  if (!content.trim()) {
+    logger.warn(formatCompact({ op: 'qq_outbound_markdown_dropped', reason: 'empty_content' }));
+    return null;
+  }
+  return { type: 'markdown', data: { content } };
+}
+
+function coreButtonToQq(btn: QqOutboundButtonSpec): Record<string, unknown> {
+  const isCommand = btn.mode === 'command';
+  const action: Record<string, unknown> = {
+    type: isCommand ? 2 : 0,
+    permission: { type: 2 },
+    data: btn.payload ?? '',
+    click_limit: btn.disabled ? 0 : 10,
+    unsupport_tips: btn.disabled ? '该按钮不可用' : '',
+  };
+  if (isCommand) {
+    if (btn.command?.enter != null) action.enter = btn.command.enter;
+    if (btn.command?.reply != null) action.reply = btn.command.reply;
+  }
+  return {
+    id: btn.id ?? '',
+    render_data: {
+      label: btn.label ?? '',
+      visited_label: btn.label ?? '',
+      style: btn.style === 'primary' ? 1 : btn.style === 'danger' ? 2 : 0,
+    },
+    action,
+  };
+}
+
+/** keyboard 段 → 模板键盘（data.id）或 button 行段（data.rows） */
+function expandKeyboardSegment(seg: QqWireSegment): QqOutboundElem[] {
+  const data = seg.data ?? {};
+  if (typeof data.id === 'string' && data.id) {
+    return [{ type: 'keyboard', data: { id: data.id } }];
+  }
+  if (!Array.isArray(data.rows)) {
+    logger.warn(formatCompact({ op: 'qq_outbound_keyboard_dropped', reason: 'missing_rows' }));
+    return [];
+  }
+  const out: QqOutboundElem[] = [];
+  for (const row of data.rows) {
+    if (!Array.isArray(row)) continue;
+    out.push({
+      type: 'button',
+      data: {
+        buttons: row.map((btn) => coreButtonToQq((btn ?? {}) as QqOutboundButtonSpec)),
+      },
+    });
+  }
+  return out;
+}
+
+function toSegmentList(payload: unknown): Array<string | QqWireSegment> {
+  if (Array.isArray(payload)) return payload as Array<string | QqWireSegment>;
+  if (payload && typeof payload === 'object' && 'type' in payload) {
+    return [payload as QqWireSegment];
+  }
+  return [];
+}
+
+function textFromUnknownSegment(seg: QqWireSegment): string {
+  const data = seg.data ?? {};
+  return data.text != null ? String(data.text) : '';
+}
+
+/**
+ * 渲染后 payload → QQ Sendable。
+ * 纯文本输入原样返回（与既有行为一致）；含富媒体段时返回段数组。
+ */
+export function formatOutbound(payload: unknown): QqOutboundMessage {
+  if (typeof payload === 'string') return payload;
+
+  const segments = toSegmentList(payload);
+  if (segments.length === 0) {
+    return payload == null
+      ? ''
+      : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload);
+  }
+
+  // QQ 按钮消息必须携带 markdown（msg_type=2），keyboard 存在时文本合并为 markdown 段
+  const hasKeyboard = segments.some(
+    (item) => typeof item !== 'string' && item.type === 'keyboard',
+  );
+
+  const parts: Array<string | QqOutboundElem> = [];
+  let textBuf = '';
+  const flushText = (): void => {
+    if (!textBuf) return;
+    parts.push(hasKeyboard
+      ? { type: 'markdown', data: { content: textBuf } }
+      : textBuf);
+    textBuf = '';
+  };
+
+  for (const item of segments) {
+    if (typeof item === 'string') {
+      textBuf += item;
+      continue;
+    }
+    const data = item.data ?? {};
+    switch (item.type) {
+      case 'text':
+        textBuf += String(data.text ?? data.content ?? '');
+        break;
+      case 'at': {
+        const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+        if (!id) break;
+        flushText();
+        parts.push({ type: 'at', data: { user_id: id } });
+        break;
+      }
+      case 'image':
+      case 'audio':
+      case 'video':
+      case 'file': {
+        flushText();
+        const media = normalizeMediaSegment(item);
+        if (media) parts.push(media);
+        break;
+      }
+      case 'markdown': {
+        flushText();
+        const markdown = normalizeMarkdownSegment(item);
+        if (markdown) parts.push(markdown);
+        break;
+      }
+      case 'keyboard': {
+        flushText();
+        parts.push(...expandKeyboardSegment(item));
+        break;
+      }
+      case 'reply': {
+        const id = data.id ?? data.event_id;
+        if (id == null || id === '') break;
+        flushText();
+        parts.push({
+          type: 'reply',
+          data: data.event_id != null
+            ? { event_id: String(data.event_id) }
+            : { id: String(id) },
+        });
+        break;
+      }
+      default:
+        // 未识别段：保持既有文本降级
+        textBuf += textFromUnknownSegment(item);
+        break;
+    }
+  }
+  flushText();
+
+  if (parts.length === 0) return '';
+  if (parts.length === 1) return parts[0]!;
+  return parts;
+}