@zhin.js/adapter-qq 7.0.3 → 7.0.5

package/middlewares/bot-kind-reply.js

@@ -0,0 +1,46 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineMiddleware } from '@zhin.js/middleware';
+import { completeQqPendingBotKind, } from "../lib/qq-endpoint-commands.js";
+import { parseQqBotKindAnswer, qqCommandSessionKey, QQ_BOT_KIND_PROMPT, } from "../lib/qq-bot-kind-prompt.js";
+import { qqRuntimeStateToken } from "../lib/qq-runtime-state.js";
+/**
+ * 扫码绑定成功后，在同一会话收取 public/private（或 公域/私域）回复并写入 intents。
+ * 非待确认会话、或内容无法识别为 botKind 时放行后续中间件/命令。
+ */
+export default defineMiddleware({
+    target: 'inbound',
+    phase: 'before-dispatch',
+    order: -50,
+    async handle(context, next) {
+        const state = context.use(qqRuntimeStateToken);
+        const pending = state.pendingBotKind;
+        if (!pending) {
+            await next();
+            return;
+        }
+        const sessionKey = qqCommandSessionKey(context.input);
+        if (!sessionKey || sessionKey !== pending.sessionKey) {
+            await next();
+            return;
+        }
+        const raw = String(context.input.content ?? '').trim();
+        // 让 qq.endpoint cancel 等命令继续走命令链
+        if (raw.toLowerCase().startsWith('qq.endpoint')) {
+            await next();
+            return;
+        }
+        const botKind = parseQqBotKindAnswer(raw);
+        if (!botKind) {
+            await context.input.$reply?.(`未识别「${raw}」。${QQ_BOT_KIND_PROMPT}`);
+            return;
+        }
+        try {
+            const text = completeQqPendingBotKind(pending, botKind);
+            state.pendingBotKind = null;
+            await context.input.$reply?.(text);
+        }
+        catch (error) {
+            await context.input.$reply?.(`写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});

package/middlewares/bot-kind-reply.ts

@@ -0,0 +1,60 @@
+import { defineMiddleware } from '@zhin.js/middleware';
+import type { CommandMessage } from '@zhin.js/command';
+import {
+  completeQqPendingBotKind,
+} from '../src/qq-endpoint-commands.js';
+import {
+  parseQqBotKindAnswer,
+  qqCommandSessionKey,
+  QQ_BOT_KIND_PROMPT,
+} from '../src/qq-bot-kind-prompt.js';
+import { qqRuntimeStateToken } from '../src/qq-runtime-state.js';
+
+/**
+ * 扫码绑定成功后，在同一会话收取 public/private（或 公域/私域）回复并写入 intents。
+ * 非待确认会话、或内容无法识别为 botKind 时放行后续中间件/命令。
+ */
+export default defineMiddleware<CommandMessage>({
+  target: 'inbound',
+  phase: 'before-dispatch',
+  order: -50,
+  async handle(context, next) {
+    const state = context.use(qqRuntimeStateToken);
+    const pending = state.pendingBotKind;
+    if (!pending) {
+      await next();
+      return;
+    }
+
+    const sessionKey = qqCommandSessionKey(context.input);
+    if (!sessionKey || sessionKey !== pending.sessionKey) {
+      await next();
+      return;
+    }
+
+    const raw = String(context.input.content ?? '').trim();
+    // 让 qq.endpoint cancel 等命令继续走命令链
+    if (raw.toLowerCase().startsWith('qq.endpoint')) {
+      await next();
+      return;
+    }
+
+    const botKind = parseQqBotKindAnswer(raw);
+    if (!botKind) {
+      await context.input.$reply?.(
+        `未识别「${raw}」。${QQ_BOT_KIND_PROMPT}`,
+      );
+      return;
+    }
+
+    try {
+      const text = completeQqPendingBotKind(pending, botKind);
+      state.pendingBotKind = null;
+      await context.input.$reply?.(text);
+    } catch (error) {
+      await context.input.$reply?.(
+        `写入配置失败：${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "7.0.3",
+  "version": "7.0.5",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,21 +35,23 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@zhin.js/adapter": "1.1.5",
-    "@zhin.js/command": "1.0.7",
-    "@zhin.js/core": "1.5.2",
-    "@zhin.js/host-http": "1.0.6",
-    "@zhin.js/im-contract": "1.0.1",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.3"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/command": "1.0.9",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/host-http": "1.0.8",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/middleware": "1.0.8",
+    "@zhin.js/permission": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.5",
-    "@zhin.js/agent": "1.1.3",
-    "@zhin.js/core": "1.5.2",
-    "@zhin.js/plugin-runtime": "1.1.3",
-    "zhin.js": "6.0.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/agent": "1.1.5",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -67,13 +69,14 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.3",
-    "@zhin.js/host-http": "1.0.6",
-    "zhin.js": "6.0.2"
+    "@zhin.js/agent": "1.1.5",
+    "@zhin.js/host-http": "1.0.8",
+    "zhin.js": "6.0.4"
   },
   "files": [
     "adapters",
     "commands",
+    "middlewares",
     "plugin.js",
     "schema.json",
     "src",
@@ -103,6 +106,10 @@
       {
         "package": "@zhin.js/command",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/middleware",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.js

@@ -1,6 +1,7 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { definePlugin } from '@zhin.js/plugin-runtime';
-import { registerQqPlatformPermitChecker } from "./lib/platform-permit.js";
+import { permissionHostToken } from '@zhin.js/permission';
+import { checkQqPlatformPermit } from "./lib/platform-permit.js";
 import { createQqRuntimeState, qqRuntimeStateToken } from "./lib/qq-runtime-state.js";
 export default definePlugin({
     name: 'qq',
@@ -8,9 +9,10 @@ export default definePlugin({
         displayName: 'QQ Official WebSocket Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表 + 扫码绑定单例，供 adapter create 与 `qq.endpoint` 命令共享
         context.resources.provide(qqRuntimeStateToken, createQqRuntimeState());
-        // 平台权限门禁：guild_owner / guild_admin / manage_roles / manage_channels（agent 工具 platformPermit）
-        return registerQqPlatformPermitChecker();
+        if (context.resources.has(permissionHostToken)) {
+            const host = context.resources.use(permissionHostToken);
+            return host.registerPlatform('qq', checkQqPlatformPermit);
+        }
     },
 });

package/schema.json

@@ -17,15 +17,39 @@
       "type": "boolean",
       "default": false
     },
+    "botKind": {
+      "type": "string",
+      "enum": [
+        "public",
+        "private"
+      ],
+      "default": "public",
+      "description": "公域/私域：均含 GROUP_AND_C2C_EVENT；频道消息分别为 PUBLIC_GUILD_MESSAGES / GUILD_MESSAGES。未显式配置 intents 时按此展开"
+    },
     "master": {
-      "type": ["string", "number"],
-      "description": "Endpoint Owner（qq endpoint 管理命令权限、AI master 角色）；endpoints[i] 可逐项覆盖"
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（endpoint 管理命令、AI/工具权限）；openid。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted openid"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
     },
     "intents": {
       "type": "array",
       "items": {
         "type": "string"
-      }
+      },
+      "description": "WebSocket Identify intents；省略时按 botKind 自动生成（public→含 PUBLIC_GUILD_MESSAGES）"
     },
     "accessTokenUrl": {
       "type": "string"
@@ -48,15 +72,11 @@
     },
     "endpoints": {
       "type": "array",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
-          "name": {
-            "type": "string",
-            "description": "QQ bot name"
-          },
           "appid": {
             "type": "string",
             "description": "QQ official bot app ID"
@@ -64,10 +84,47 @@
           "secret": {
             "type": "string",
             "description": "QQ official bot secret"
+          },
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（openid）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted openid"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "botKind": {
+            "type": "string",
+            "enum": [
+              "public",
+              "private"
+            ],
+            "description": "覆盖顶层 botKind（公域/私域），用于按 endpoint 生成 intents"
+          },
+          "intents": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "覆盖顶层 intents"
+          },
+          "id": {
+            "type": "string",
+            "description": "QQ bot name"
           }
         },
         "required": [
-          "name",
+          "id",
           "appid",
           "secret"
         ]

package/src/endpoint.ts

@@ -9,7 +9,7 @@ import type {
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { formatOutbound } from './outbound.js';
 import { registerQqAgentEndpoint } from './qq-agent-deps.js';
@@ -38,8 +38,6 @@ import {
   type QqBotTransport,
 } from './ws.js';
 
-const logger = getLogger('qq');
-
 export type { CreateQqBot, QqBotTransport } from './ws.js';
 export type { CreateQqHttpBot, QqHttpBotTransport } from './webhook.js';
 
@@ -51,6 +49,8 @@ export interface QqEndpointOptions {
 }
 
 export class QqWebsocketEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: QqEndpointOptions;
   readonly #createBot: CreateQqBot;
   #bot: QqBotTransport | null = null;
@@ -60,32 +60,30 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   readonly management: EndpointManagement = createQqEndpointManagement(this);
 
   constructor(options: QqEndpointOptions) {
+    this.#logger = getAdapterLogger('qq', options.config.id);
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateBot;
   }
 
   /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
   get name(): string {
-    return this.#options.config.name;
+    return this.#options.config.id;
   }
 
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
     try {
-      this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.name, this);
+      this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.id, this);
       this.#bot = this.#createBot(this.#options.config);
       this.#bindBot(this.#bot);
       await this.#bot.start();
-      logger.info(formatCompact({
-        op: 'connect',
-        endpoint: this.#options.config.name,
-        mode: 'websocket',
-        appid: this.#options.config.appid,
-      }));
+      this.#logger.info(
+        `connected (websocket) | appid: ${this.#options.config.appid}`,
+      );
     } catch (error) {
       await this.stop();
-      logger.error('Failed to connect QQ websocket:', error);
+      this.#logger.error('Failed to connect QQ websocket:', error);
       const raw = error instanceof Error ? error.message : String(error);
       throw new Error(
         `QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`,
@@ -116,7 +114,7 @@ export class QqWebsocketEndpoint implements EndpointInstance {
       this.#bot = null;
     }
     this.#started = false;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
@@ -140,12 +138,11 @@ export class QqWebsocketEndpoint implements EndpointInstance {
         break;
     }
     const messageId = `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
-    logger.debug(formatCompact({
-      op: 'qq_send',
-      endpoint: this.#options.config.name,
-      target: `${kind}:${conversation.id}`,
-      messageId,
-    }));
+    this.#logger.info(
+      `send ${kind}:${conversation.id}`
+      + ` | id: ${messageId}`
+      + ` | ${truncatePreview(typeof body === 'string' ? body : String(body), 80)}`,
+    );
     return messageId;
   }
 
@@ -166,9 +163,9 @@ export class QqWebsocketEndpoint implements EndpointInstance {
         await bot.recallDirectMessage?.(channelId, qqMsgId);
         break;
     }
-    logger.debug(formatCompact({
+    this.#logger.debug(formatCompact({
       op: 'qq_recall',
-      endpoint: this.#options.config.name,
+      endpoint: this.#options.config.id,
       kind,
       messageId,
     }));
@@ -178,23 +175,33 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   admit(msg: QqInboundMessage): void {
     if (!this.#open) return;
     const conversation = qqInboundConversation(String(this.#options.id), msg);
+    const content = formatInboundContent(msg);
+    this.#logger.info(
+      `recv ${conversation.kind}:${conversation.id}`
+      + (msg.authorId ? ` from ${msg.authorId}` : '')
+      + (msg.mentioned ? ' (mentioned)' : '')
+      + ` | ${truncatePreview(content, 80)}`,
+    );
     void this.#options.gateway.receive({
       conversation,
       message: { conversation, id: msg.id },
-      content: formatInboundContent(msg),
+      content,
       ...(msg.segments?.length ? { segments: msg.segments } : {}),
-      sender: senderDisplayName(msg),
+      sender: {
+        id: msg.authorId,
+        name: senderDisplayName(msg) || undefined,
+        ...(msg.authorRoles?.length ? { roles: msg.authorRoles } : {}),
+      },
+      endpointId: this.#options.config.id,
+      ...(msg.mentioned ? { mentioned: true } : {}),
       metadata: Object.freeze({
-        endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
         userId: msg.authorId,
         guildId: msg.guildId,
         roles: msg.authorRoles,
-        // AT 事件本身即 @ 机器人；新 Runtime 纯文本 content 需经 metadata 传递
-        ...(msg.mentioned ? { mentioned: true } : {}),
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'qq_gateway_receive_failed',
         target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
@@ -257,6 +264,8 @@ export interface QqHttpEndpointOptions {
 
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
 export class QqHttpEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: QqHttpEndpointOptions;
   readonly #createBot: CreateQqHttpBot;
   #bot: QqHttpBotTransport | null = null;
@@ -267,13 +276,14 @@ export class QqHttpEndpoint implements EndpointInstance {
   readonly management: EndpointManagement = createQqEndpointManagement(this);
 
   constructor(options: QqHttpEndpointOptions) {
+    this.#logger = getAdapterLogger('qq', options.config.id);
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateHttpBot;
   }
 
   /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
   get name(): string {
-    return this.#options.config.name;
+    return this.#options.config.id;
   }
 
   async start(): Promise<void> {
@@ -281,22 +291,19 @@ export class QqHttpEndpoint implements EndpointInstance {
     this.#started = true;
     try {
       this.#unregisterAgent = registerQqAgentEndpoint(
-        this.#options.config.name,
+        this.#options.config.id,
         this as unknown as QqWebsocketEndpoint,
       );
       this.#setupRoutes();
       this.#bot = this.#createBot(this.#options.config);
       this.#bindBot(this.#bot);
       await this.#bot.start();
-      logger.info(formatCompact({
-        op: 'connect',
-        endpoint: this.#options.config.name,
-        mode: this.#options.config.mode,
-        path: this.#options.config.webhookPath,
-      }));
+      this.#logger.info(
+        `connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`,
+      );
     } catch (error) {
       await this.stop();
-      logger.error('Failed to connect QQ HTTP receiver:', error);
+      this.#logger.error('Failed to connect QQ HTTP receiver:', error);
       throw error;
     }
   }
@@ -324,7 +331,7 @@ export class QqHttpEndpoint implements EndpointInstance {
       this.#bot = null;
     }
     this.#started = false;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
@@ -347,7 +354,13 @@ export class QqHttpEndpoint implements EndpointInstance {
         result = await bot.sendDirectMessage(conversation.id, body);
         break;
     }
-    return `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
+    const messageId = `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
+    this.#logger.info(
+      `send ${kind}:${conversation.id}`
+      + ` | id: ${messageId}`
+      + ` | ${truncatePreview(typeof body === 'string' ? body : String(body), 80)}`,
+    );
+    return messageId;
   }
 
   async recallMessage(messageId: string): Promise<void> {
@@ -367,9 +380,9 @@ export class QqHttpEndpoint implements EndpointInstance {
         await bot.recallDirectMessage?.(channelId, qqMsgId);
         break;
     }
-    logger.debug(formatCompact({
+    this.#logger.debug(formatCompact({
       op: 'qq_recall',
-      endpoint: this.#options.config.name,
+      endpoint: this.#options.config.id,
       kind,
       messageId,
     }));
@@ -378,23 +391,33 @@ export class QqHttpEndpoint implements EndpointInstance {
   admit(msg: QqInboundMessage): void {
     if (!this.#open) return;
     const conversation = qqInboundConversation(String(this.#options.id), msg);
+    const content = formatInboundContent(msg);
+    this.#logger.info(
+      `recv ${conversation.kind}:${conversation.id}`
+      + (msg.authorId ? ` from ${msg.authorId}` : '')
+      + (msg.mentioned ? ' (mentioned)' : '')
+      + ` | ${truncatePreview(content, 80)}`,
+    );
     void this.#options.gateway.receive({
       conversation,
       message: { conversation, id: msg.id },
-      content: formatInboundContent(msg),
+      content,
       ...(msg.segments?.length ? { segments: msg.segments } : {}),
-      sender: senderDisplayName(msg),
+      sender: {
+        id: msg.authorId,
+        name: senderDisplayName(msg) || undefined,
+        ...(msg.authorRoles?.length ? { roles: msg.authorRoles } : {}),
+      },
+      endpointId: this.#options.config.id,
+      ...(msg.mentioned ? { mentioned: true } : {}),
       metadata: Object.freeze({
-        endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
         userId: msg.authorId,
         guildId: msg.guildId,
         roles: msg.authorRoles,
-        // AT 事件本身即 @ 机器人；新 Runtime 纯文本 content 需经 metadata 传递
-        ...(msg.mentioned ? { mentioned: true } : {}),
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'qq_gateway_receive_failed',
         target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),

package/src/index.ts

@@ -13,6 +13,16 @@ export {
   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,
@@ -58,5 +68,4 @@ export {
   normalizeQqGuildSenderForPermit,
   platformPermit,
   qqGuildPermitResolver,
-  registerQqPlatformPermitChecker,
 } from './platform-permit.js';

package/src/platform-permit.ts

@@ -1,7 +1,7 @@
 /**
  * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
  */
-import { registerPlatformPermitChecker, type Message } from '@zhin.js/core';
+import type { PermissionSubject } from '@zhin.js/permission';
 
 const ADAPTER = 'qq';
 
@@ -36,10 +36,9 @@ export function normalizeQqGuildSenderForPermit(input: {
   return { role: 'member', permissions };
 }
 
-export function checkQqPlatformPermit(perm: string, message: Message<any>): boolean {
-  const sender = message.$sender as { role?: string; permissions?: string[] };
-  const permissions = sender.permissions ?? [];
-  const role = sender.role;
+export function checkQqPlatformPermit(perm: string, subject: PermissionSubject): boolean {
+  const role = subject.sender?.role?.[0];
+  const permissions = subject.sender?.permissions ?? [];
   const has = (t: string) => permissions.includes(t);
 
   switch (perm) {
@@ -55,7 +54,3 @@ export function checkQqPlatformPermit(perm: string, message: Message<any>): bool
       return false;
   }
 }
-
-export function registerQqPlatformPermitChecker(): () => void {
-  return registerPlatformPermitChecker(ADAPTER, checkQqPlatformPermit);
-}