@zhin.js/adapter-qq 2.0.12 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "2.0.12",
+  "version": "3.0.1",
   "description": "Zhin.js adapter for QQ Official Bot",
   "type": "module",
   "main": "./lib/index.js",
@@ -41,18 +41,21 @@
     "@types/react-dom": "^19.2.3",
     "lucide-react": "^1.17.0",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.88",
-    "@zhin.js/host-api": "0.0.4",
-    "zhin.js": "1.0.93",
-    "@zhin.js/contract": "1.0.1"
+    "@zhin.js/cli": "1.0.89",
+    "@zhin.js/client": "2.0.3",
+    "@zhin.js/contract": "1.0.1",
+    "@zhin.js/host-api": "1.0.1",
+    "@zhin.js/host-router": "1.0.1",
+    "@zhin.js/logger": "0.1.71",
+    "zhin.js": "2.0.1"
   },
   "peerDependencies": {
-    "@zhin.js/client": "2.0.2",
-    "@zhin.js/host-api": "0.0.4",
-    "@zhin.js/host-router": "0.0.3",
+    "@zhin.js/client": "2.0.3",
+    "@zhin.js/host-api": "1.0.1",
     "@zhin.js/contract": "1.0.1",
-    "@zhin.js/logger": "0.1.70",
-    "zhin.js": "1.0.93"
+    "@zhin.js/host-router": "1.0.1",
+    "@zhin.js/logger": "0.1.71",
+    "zhin.js": "2.0.1"
   },
   "peerDependenciesMeta": {
     "@zhin.js/client": {

package/skills/qq/PERMITS.md

@@ -0,0 +1,25 @@
+# QQ 官方频道 Platform Permits
+
+> 与 QQ 群 `group_*` **分开命名**，仅用于 guild/channel 场景。
+
+## 入站字段
+
+`message_type === guild` 时 `getGuildMember` + `getGuildInfo`（TTL 60s）：
+
+| 字段 | 取值 |
+|------|------|
+| `$sender.role` | `owner` · `admin` · `member` |
+| `$sender.permissions` | `guild_owner` · `guild_admin` · `manage_roles` · `manage_channels` · 角色 ID |
+
+## Permit 词汇表
+
+| `platform(qq,…)` | 含义 |
+|------------------|------|
+| `guild_owner` | 频道主 |
+| `guild_admin` | 频道管理员 |
+| `manage_roles` | 管理身份组 |
+| `manage_channels` | 管理子频道 |
+
+## 工厂映射
+
+`group_admin` → `guild_admin` · `group_owner` → `guild_owner`

package/skills/qq/SKILL.md

@@ -5,7 +5,7 @@ platforms:
 description: >-
   QQ 官方机器人管理能力。当用户在 QQ 官方机器人（非 OneBot/NapCat）中请求群管（踢人、
   禁言、全员禁言）、频道/子频道管理、角色管理（创建/添加/移除角色）、
-  或查询成员详情时使用。即使用户没有明确提到 QQ 官方机器人，只要 Bot 平台是 qq
+  或查询成员详情时使用。即使用户没有明确提到 QQ 官方机器人，只要 Endpoint 平台是 qq
   （官方 API）且涉及上述操作，就应触发。仅有昵称时先 list_members 查 user_id。
 keywords:
   - qq

package/src/adapter.ts

@@ -6,10 +6,12 @@ import {
   Plugin,
 } from "zhin.js";
 import type { Router } from "@zhin.js/host-router";
-import { QQBot } from "./bot.js";
-import type { QQBotConfig, ReceiverMode } from "./types.js";
+import { QQEndpoint } from "./endpoint.js";
+import type { QQEndpointConfig, ReceiverMode } from "./types.js";
+
+export class QQAdapter extends Adapter<QQEndpoint<ReceiverMode>> {
+  static override readonly capabilities = ['inbound', 'outbound'] as const;
 
-export class QQAdapter extends Adapter<QQBot<ReceiverMode>> {
   #router?: Router;
 
   constructor(plugin: Plugin, router?: Router) {
@@ -21,40 +23,40 @@ export class QQAdapter extends Adapter<QQBot<ReceiverMode>> {
     return this.#router;
   }
 
-  createBot(config: QQBotConfig<ReceiverMode>): QQBot<ReceiverMode> {
-    return new QQBot(this, config);
+  createEndpoint(config: QQEndpointConfig<ReceiverMode>): QQEndpoint<ReceiverMode> {
+    return new QQEndpoint(this, config);
   }
 
   // ── IGroupManagement 标准群管方法 ──────────────────────────────────
 
-  async kickMember(botId: string, sceneId: string, userId: string) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.removeGuildMember(sceneId, userId, false);
+  async kickMember(endpointId: string, sceneId: string, userId: string) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.removeGuildMember(sceneId, userId, false);
   }
 
-  async muteMember(botId: string, sceneId: string, userId: string, duration = 600) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.muteMembers(sceneId, [userId], duration);
+  async muteMember(endpointId: string, sceneId: string, userId: string, duration = 600) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.muteMembers(sceneId, [userId], duration);
   }
 
-  async muteAll(botId: string, sceneId: string, enable = true) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.muteAll(sceneId, enable ? 600 : 0);
+  async muteAll(endpointId: string, sceneId: string, enable = true) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.muteAll(sceneId, enable ? 600 : 0);
   }
 
-  async listMembers(botId: string, sceneId: string) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.getGuildMembers(sceneId);
+  async listMembers(endpointId: string, sceneId: string) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.getGuildMembers(sceneId);
   }
 
-  async getGroupInfo(botId: string, sceneId: string) {
-    const bot = this.bots.get(botId);
-    if (!bot) throw new Error(`Bot ${botId} 不存在`);
-    return bot.getGuildInfo(sceneId);
+  async getGroupInfo(endpointId: string, sceneId: string) {
+    const endpoint = this.endpoints.get(endpointId);
+    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return endpoint.getGuildInfo(sceneId);
   }
 
   // ── 生命周期 ───────────────────────────────────────────────────────

package/src/{bot.ts → endpoint.ts}

@@ -1,8 +1,8 @@
 /**
- * QQ 官方 Bot 实现
+ * QQ 官方 Endpoint 实现
  */
 import {
-  Bot,
+  Bot as QQOfficialClient,
   PrivateMessageEvent,
   GroupMessageEvent,
 } from "qq-official-bot";
@@ -10,14 +10,14 @@ import path from "path";
 import { formatCompact } from "@zhin.js/logger";
 import { registerFetchRoute, type RouterContext } from "@zhin.js/host-router/router";
 import {
-  Bot as ZhinBot,
+  Endpoint,
   Message,
   SendOptions,
   SendContent,
   segment,
 } from "zhin.js";
 import type { MessageElement } from "zhin.js";
-import { ReceiverMode, type QQBotConfig, type ApplicationPlatform } from "./types.js";
+import { ReceiverMode, type QQEndpointConfig, type ApplicationPlatform } from "./types.js";
 import type { QQAdapter } from "./adapter.js";
 import { normalizeQqInboundWsPayload, type QqWsPacket } from "./inbound-normalize.js";
 import { normalizeGroupAtPrefix } from "./group-at-normalize.js";
@@ -25,14 +25,37 @@ import { SDK_VERSION, SDK_VERSION_HEADER } from "./sdk-version.js";
 import { applyCustomAuthEndpoints } from "./gateway-config.js";
 import { normalizeOutboundMarkdown } from "./outbound-markdown.js";
 import { normalizeOutboundMedia } from "./outbound-media.js";
+import { normalizeQqGuildSenderForPermit } from "./platform-permit.js";
 
+/** 从 qq-official-bot SendResult / 审核回包中解析出站消息 ID */
+export function resolveOutboundMessageId(result: unknown): string {
+  if (!result || typeof result !== "object") {
+    throw new Error("QQ 发送消息失败：响应为空");
+  }
+  const row = result as Record<string, unknown>;
+  const nested = row.data && typeof row.data === "object"
+    ? row.data as Record<string, unknown>
+    : undefined;
+  const audit = (row.message_audit ?? nested?.message_audit) as Record<string, unknown> | undefined;
+  const id = row.id ?? row.message_id ?? audit?.audit_id;
+  if (id == null || id === "") {
+    const code = row.code;
+    const msg = row.message;
+    throw new Error(
+      code != null
+        ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ""}`
+        : "QQ 发送消息失败：响应缺少消息 ID",
+    );
+  }
+  return String(id);
+}
 
-export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = ApplicationPlatform>
-  extends Bot
-  implements ZhinBot<QQBotConfig<T, M>, PrivateMessageEvent | GroupMessageEvent>
+export class QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform = ApplicationPlatform>
+  extends QQOfficialClient
+  implements Endpoint<QQEndpointConfig<T, M>, PrivateMessageEvent | GroupMessageEvent>
 {
   $connected: boolean = false;
-  declare $config: QQBotConfig<T, M>;
+  declare $config: QQEndpointConfig<T, M>;
   /** 平台侧机器人 user_id，用于 @ 触发匹配 */
   $platformUserId?: string;
 
@@ -44,10 +67,10 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     return this.$config.name;
   }
 
-  constructor(public adapter: QQAdapter, config: QQBotConfig<T, M>) {
+  constructor(public adapter: QQAdapter, config: QQEndpointConfig<T, M>) {
     if (!config.data_dir) config.data_dir = path.join(process.cwd(), "data");
     if (config.mode === ReceiverMode.MIDDLEWARE) {
-      const mw = config as QQBotConfig<ReceiverMode.MIDDLEWARE, M> & {
+      const mw = config as QQEndpointConfig<ReceiverMode.MIDDLEWARE, M> & {
         platform?: ApplicationPlatform;
       };
       if (!mw.platform) {
@@ -84,9 +107,60 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     super.dispatchEvent(event, wsRes);
   }
 
-  private handleQQMessage(msg: PrivateMessageEvent | GroupMessageEvent): void {
+  private guildMemberCache = new Map<string, { at: number; role?: string; permissions: string[] }>();
+  private guildOwnerCache = new Map<string, { at: number; ownerId?: string }>();
+
+  private async enrichGuildSender(
+    message: ReturnType<QQEndpoint<ReceiverMode>["$formatMessage"]>,
+    guildId: string,
+    userId: string,
+  ): Promise<void> {
+    const key = `${guildId}:${userId}`;
+    const now = Date.now();
+    const cached = this.guildMemberCache.get(key);
+    if (cached && now - cached.at < 60_000) {
+      message.$sender.role = cached.role;
+      message.$sender.permissions = cached.permissions;
+      return;
+    }
+    try {
+      let ownerId: string | undefined;
+      const ownerCached = this.guildOwnerCache.get(guildId);
+      if (ownerCached && now - ownerCached.at < 300_000) {
+        ownerId = ownerCached.ownerId;
+      } else {
+        const guild = await this.getGuildInfo(guildId);
+        ownerId = guild?.owner_id?.toString?.() ?? guild?.owner?.id?.toString?.();
+        this.guildOwnerCache.set(guildId, { at: now, ownerId });
+      }
+      const member = await this.getGuildMember(guildId, userId);
+      const roleIds = Array.isArray(member?.roles)
+        ? member.roles.map((r: unknown) =>
+            typeof r === "string" ? r : (r as { id?: string })?.id ?? String(r),
+          )
+        : [];
+      const isOwner = ownerId === userId;
+      const isAdmin = !isOwner && roleIds.length > 0;
+      const normalized = normalizeQqGuildSenderForPermit({ roles: roleIds, isOwner, isAdmin });
+      const entry = {
+        at: now,
+        role: normalized.role,
+        permissions: normalized.permissions ?? [],
+      };
+      this.guildMemberCache.set(key, entry);
+      message.$sender.role = entry.role;
+      message.$sender.permissions = entry.permissions;
+    } catch {
+      // 保守拒绝
+    }
+  }
+
+  private async handleQQMessage(msg: PrivateMessageEvent | GroupMessageEvent): Promise<void> {
     try {
       const message = this.$formatMessage(msg);
+      if (msg.message_type === "guild" && msg.guild_id && message.$sender.id) {
+        await this.enrichGuildSender(message, String(msg.guild_id), message.$sender.id);
+      }
       this.adapter.emit("message.receive", message);
       this.pluginLogger.debug(
         `${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`,
@@ -128,7 +202,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
   }
 
   async $disconnect(): Promise<void> {
-    // Bot 继承自 EventEmitter，清除 $connect() 注册的所有监听器
+    // Endpoint 继承自 EventEmitter，清除 $connect() 注册的所有监听器
     (this as unknown as import('node:events').EventEmitter).removeAllListeners();
     await this.stop();
     this.$connected = false;
@@ -168,7 +242,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
       return;
     }
     if (mode === ReceiverMode.WEBHOOK) {
-      const cfg = this.$config as QQBotConfig<ReceiverMode.WEBHOOK>;
+      const cfg = this.$config as QQEndpointConfig<ReceiverMode.WEBHOOK>;
       this.pluginLogger.info(formatCompact({
         op: "webhook",
         mode: "standalone",
@@ -203,16 +277,16 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
 
     let content = msg.message;
     if (msg.message_type === "group" && Array.isArray(content)) {
-      const botAtIds = [this.$platformUserId, this.$config.appid]
+      const endpointAtIds = [this.$platformUserId, this.$config.appid]
         .filter((id): id is string => Boolean(id))
         .map(String);
-      content = normalizeGroupAtPrefix(content, botAtIds, raw.__zhin_group_at === true);
+      content = normalizeGroupAtPrefix(content, endpointAtIds, raw.__zhin_group_at === true);
     }
 
     const result = Message.from(msg, {
       $id: msg.message_id?.toString(),
       $adapter: "qq" as const,
-      $bot: this.$config.name,
+      $endpoint: this.$config.name,
       $sender: {
         id: msg.sender.user_id?.toString(),
         name: msg.sender.user_name?.toString(),
@@ -233,7 +307,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
         return await this.adapter.sendMessage({
           ...result.$channel,
           context: "qq",
-          bot: this.$config.name,
+          endpoint: this.$config.name,
           content,
         });
       },
@@ -252,22 +326,22 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
           const id = options.id.replace("direct:", "");
           const result = await this.sendDirectMessage(id, content);
           this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
-          return `direct-${options.id}:${result.id.toString()}`;
+          return `direct-${options.id}:${resolveOutboundMessageId(result)}`;
         } else {
           const result = await this.sendPrivateMessage(options.id, content);
           this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
-          return `private-${options.id}:${result.id.toString()}`;
+          return `private-${options.id}:${resolveOutboundMessageId(result)}`;
         }
       }
       case "group": {
         const result = await this.sendGroupMessage(options.id, content);
         this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
-        return `group-${options.id}:${result.id.toString()}`;
+        return `group-${options.id}:${resolveOutboundMessageId(result)}`;
       }
       case "channel": {
         const result = await this.sendGuildMessage(options.id, content);
         this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
-        return `channel-${options.id}:${result.id.toString()}`;
+        return `channel-${options.id}:${resolveOutboundMessageId(result)}`;
       }
       default:
         throw new Error(`unsupported channel type ${options.type}`);
@@ -294,7 +368,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       return await this.guildService.getList();
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 获取频道列表失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取频道列表失败:`, error);
       throw error;
     }
   }
@@ -307,7 +381,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       return await this.guildService.getInfo(guildId);
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 获取频道详情失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取频道详情失败:`, error);
       throw error;
     }
   }
@@ -320,7 +394,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       return await this.channelService.getList(guildId);
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 获取子频道列表失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取子频道列表失败:`, error);
       throw error;
     }
   }
@@ -333,7 +407,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       return await this.channelService.getInfo(channelId);
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 获取子频道详情失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取子频道详情失败:`, error);
       throw error;
     }
   }
@@ -346,7 +420,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       return await this.memberService.getGuildMemberList(guildId);
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 获取频道成员列表失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取频道成员列表失败:`, error);
       throw error;
     }
   }
@@ -360,7 +434,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       return await this.memberService.getGuildMemberInfo(guildId, userId);
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 获取成员详情失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取成员详情失败:`, error);
       throw error;
     }
   }
@@ -375,10 +449,10 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
   async removeGuildMember(guildId: string, userId: string, addBlacklist?: boolean, deleteHistoryMsg?: -1 | 0 | 3 | 7 | 15 | 30): Promise<boolean> {
     try {
       await this.memberService.kickMember(guildId, userId, deleteHistoryMsg, addBlacklist);
-      this.pluginLogger.info(`QQ Bot ${this.$id} 踢出成员 ${userId}（频道 ${guildId}）`);
+      this.pluginLogger.info(`QQ Endpoint ${this.$id} 踢出成员 ${userId}（频道 ${guildId}）`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 踢出成员失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 踢出成员失败:`, error);
       throw error;
     }
   }
@@ -391,7 +465,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       return await this.guildService.getRoles(guildId);
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 获取角色列表失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 获取角色列表失败:`, error);
       throw error;
     }
   }
@@ -406,10 +480,10 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
   async createGuildRole(guildId: string, name: string, color?: number, hoist?: 0 | 1): Promise<any> {
     try {
       const result = await this.guildService.createRole(guildId, { name, color: color || 0, hoist: hoist ?? 0 });
-      this.pluginLogger.info(`QQ Bot ${this.$id} 创建角色 "${name}"（频道 ${guildId}）`);
+      this.pluginLogger.info(`QQ Endpoint ${this.$id} 创建角色 "${name}"（频道 ${guildId}）`);
       return result;
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 创建角色失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 创建角色失败:`, error);
       throw error;
     }
   }
@@ -424,10 +498,10 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
   async addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean> {
     try {
       await this.memberService.addMemberRole(guildId, channelId, userId, roleId);
-      this.pluginLogger.info(`QQ Bot ${this.$id} 给成员 ${userId} 添加角色 ${roleId}（频道 ${guildId}）`);
+      this.pluginLogger.info(`QQ Endpoint ${this.$id} 给成员 ${userId} 添加角色 ${roleId}（频道 ${guildId}）`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 添加角色失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 添加角色失败:`, error);
       throw error;
     }
   }
@@ -442,10 +516,10 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
   async removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean> {
     try {
       await this.memberService.removeMemberRole(guildId, channelId, userId, roleId);
-      this.pluginLogger.info(`QQ Bot ${this.$id} 移除成员 ${userId} 的角色 ${roleId}（频道 ${guildId}）`);
+      this.pluginLogger.info(`QQ Endpoint ${this.$id} 移除成员 ${userId} 的角色 ${roleId}（频道 ${guildId}）`);
       return true;
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 移除角色失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 移除角色失败:`, error);
       throw error;
     }
   }
@@ -460,14 +534,14 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       if (muteSeconds > 0) {
         await this.memberService.muteMembers(guildId, userIds, muteSeconds);
-        this.pluginLogger.info(`QQ Bot ${this.$id} 禁言成员 ${userIds.join(',')} ${muteSeconds}秒（频道 ${guildId}）`);
+        this.pluginLogger.info(`QQ Endpoint ${this.$id} 禁言成员 ${userIds.join(',')} ${muteSeconds}秒（频道 ${guildId}）`);
       } else {
         await this.memberService.unmuteMembers(guildId, userIds);
-        this.pluginLogger.info(`QQ Bot ${this.$id} 解除成员 ${userIds.join(',')} 禁言（频道 ${guildId}）`);
+        this.pluginLogger.info(`QQ Endpoint ${this.$id} 解除成员 ${userIds.join(',')} 禁言（频道 ${guildId}）`);
       }
       return true;
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 禁言操作失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 禁言操作失败:`, error);
       throw error;
     }
   }
@@ -481,14 +555,14 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     try {
       if (muteSeconds > 0) {
         await this.guildService.mute(guildId, muteSeconds);
-        this.pluginLogger.info(`QQ Bot ${this.$id} 开启全员禁言（频道 ${guildId}）`);
+        this.pluginLogger.info(`QQ Endpoint ${this.$id} 开启全员禁言（频道 ${guildId}）`);
       } else {
         await this.guildService.unmute(guildId);
-        this.pluginLogger.info(`QQ Bot ${this.$id} 关闭全员禁言（频道 ${guildId}）`);
+        this.pluginLogger.info(`QQ Endpoint ${this.$id} 关闭全员禁言（频道 ${guildId}）`);
       }
       return true;
     } catch (error) {
-      this.pluginLogger.error(`QQ Bot ${this.$id} 全员禁言操作失败:`, error);
+      this.pluginLogger.error(`QQ Endpoint ${this.$id} 全员禁言操作失败:`, error);
       throw error;
     }
   }

package/src/gateway-config.ts

@@ -1,8 +1,8 @@
 import type { Logger } from "@zhin.js/logger";
 import { formatCompact } from "@zhin.js/logger";
-import type { Bot } from "qq-official-bot";
+import type { Bot as QQOfficialBot } from "qq-official-bot";
 import { ReceiverMode } from "qq-official-bot";
-import type { QQBotConfig } from "./types.js";
+import type { QQEndpointConfig } from "./types.js";
 
 /** qq-official-bot 默认 token 接口 */
 export const DEFAULT_ACCESS_TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
@@ -23,15 +23,15 @@ type AuthManagerSession = {
  * SDK 仅在 websocket 模式自动读取配置；middleware / webhook 需在此补丁。
  */
 export function applyCustomAuthEndpoints(
-  bot: Bot,
-  config: Pick<QQBotConfig<ReceiverMode>, "mode" | "accessTokenUrl" | "gatewayUrl">,
+  endpoint: QQOfficialBot,
+  config: Pick<QQEndpointConfig<ReceiverMode>, "mode" | "accessTokenUrl" | "gatewayUrl">,
   logger: Logger,
 ): void {
   const { accessTokenUrl, gatewayUrl, mode } = config;
   if (!accessTokenUrl && !gatewayUrl) return;
 
   if (mode !== ReceiverMode.WEBSOCKET) {
-    const session = bot.sessionManager as unknown as AuthManagerSession;
+    const session = endpoint.sessionManager as unknown as AuthManagerSession;
     if (accessTokenUrl) session.authManager.config.accessTokenUrl = accessTokenUrl;
     if (gatewayUrl) session.authManager.config.gatewayUrl = gatewayUrl;
   }

package/src/group-at-normalize.ts

@@ -7,17 +7,17 @@ function segmentAtId(seg: MessageElement): string {
   return raw == null ? "" : String(raw);
 }
 
-function textMentionsBot(text: string, botIds: string[]): boolean {
-  for (const id of botIds) {
+function textMentionsEndpoint(text: string, endpointIds: string[]): boolean {
+  for (const id of endpointIds) {
     const re = new RegExp(`@${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
     if (re.test(text)) return true;
   }
   return false;
 }
 
-function stripInlineAtBot(text: string, botIds: string[]): string {
+function stripInlineAtEndpoint(text: string, endpointIds: string[]): string {
   let result = text;
-  for (const id of botIds) {
+  for (const id of endpointIds) {
     if (!id) continue;
     const re = new RegExp(`^@${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
     result = result.replace(re, "");
@@ -32,10 +32,10 @@ function stripInlineAtBot(text: string, botIds: string[]): string {
  */
 export function normalizeGroupAtPrefix(
   content: MessageElement[],
-  botAtIds: string[],
+  endpointAtIds: string[],
   forceAt: boolean,
 ): MessageElement[] {
-  const ids = [...new Set(botAtIds.map(String).filter(Boolean))];
+  const ids = [...new Set(endpointAtIds.map(String).filter(Boolean))];
   if (!ids.length || !Array.isArray(content)) return content;
 
   let mentioned = forceAt;
@@ -53,8 +53,8 @@ export function normalizeGroupAtPrefix(
     }
     if (seg.type === "text" && seg.data && typeof seg.data === "object") {
       const raw = String((seg.data as { text?: string }).text ?? "");
-      if (textMentionsBot(raw, ids)) mentioned = true;
-      const stripped = stripInlineAtBot(raw, ids);
+      if (textMentionsEndpoint(raw, ids)) mentioned = true;
+      const stripped = stripInlineAtEndpoint(raw, ids);
       if (stripped) {
         body.push({ ...seg, data: { ...(seg.data as object), text: stripped } });
       }