@zhin.js/adapter-qq 1.0.84 → 1.1.0

package/lib/ws.js

@@ -0,0 +1,234 @@
+/**
+ * QQ WebSocket transport: bot factory and inbound message normalization.
+ */
+import path from 'node:path';
+import { Bot, ReceiverMode, } from 'qq-official-bot';
+/**
+ * qq-official-bot 1.2 used a separate connection manager; 1.3 moved WebSocket
+ * ownership into the receiver, but Session.stop() still leaves the auth refresh
+ * manager alive. Mark the session closed, clean up legacy connections when
+ * present, stop the receiver, then destroy auth refresh at the SDK boundary.
+ */
+export async function stopQqOfficialBot(bot) {
+    const session = bot.sessionManager;
+    session.userClose = true;
+    session.connectionManager?.destroy();
+    try {
+        await bot.stop();
+    }
+    finally {
+        session.authManager?.destroy();
+    }
+}
+export function bindQqBotInboundEvents(bot, admitRaw) {
+    bot.on('message.group', admitRaw);
+    bot.on('message.guild', admitRaw);
+    bot.on('message.private', admitRaw);
+}
+export function normalizeQqMessage(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const msg = raw;
+    if (msg.message_id == null)
+        return null;
+    let channelKind = 'private';
+    let channelId = '';
+    const isGroup = msg.message_type === 'group'
+        || (msg.message_type == null && (msg.group_id != null || msg.group_openid != null));
+    const isGuild = msg.message_type === 'guild'
+        || (msg.message_type == null && !isGroup && msg.guild_id != null && msg.channel_id != null);
+    if (isGuild) {
+        channelKind = msg.sub_type === 'direct' ? 'direct' : 'channel';
+        channelId = channelKind === 'direct'
+            ? String(msg.guild_id ?? '')
+            : String(msg.channel_id ?? '');
+    }
+    else if (isGroup) {
+        channelKind = 'group';
+        channelId = String(msg.group_id ?? msg.group_openid ?? '');
+    }
+    else {
+        channelKind = 'private';
+        channelId = String(msg.user_id ?? msg.author?.user_openid ?? msg.author?.id ?? '');
+    }
+    if (!channelId)
+        return null;
+    const authorId = String(msg.sender?.user_id
+        ?? msg.user_id
+        ?? msg.author?.member_openid
+        ?? msg.author?.user_openid
+        ?? msg.author?.id
+        ?? '');
+    const content = extractTextContent(msg.message) || msg.raw_message || '';
+    const segments = extractCanonicalSegments(msg.message);
+    const rawRoles = msg.member?.roles ?? msg.sender?.roles;
+    const authorRoles = Array.isArray(rawRoles) ? rawRoles.map(String) : undefined;
+    // 统一按 mentions 判定 @：is_you 精确标识当前机器人（群载荷实测字段）。
+    // 群里 @ 另一个机器人时 mentions 带 bot:true 但无 is_you，不能误判为 @ 当前机器人，
+    // 故群场景只认 is_you；bot 回退仅限频道 AT_MESSAGE_CREATE（该事件仅 @ 当前
+    // 机器人时下发，其 mentions 无 is_you）。
+    const mentioned = Array.isArray(msg.mentions)
+        && msg.mentions.some((m) => m?.is_you === true || (m?.bot === true && channelKind !== 'group'));
+    return {
+        id: String(msg.message_id),
+        content,
+        channelKind,
+        channelId,
+        authorId,
+        authorName: msg.sender?.user_name || msg.author?.username || authorId,
+        authorRoles,
+        timestamp: Date.now(),
+        guildId: msg.guild_id != null ? String(msg.guild_id) : undefined,
+        rawMessage: msg.raw_message,
+        ...(segments.length > 0 ? { segments } : {}),
+        ...(mentioned ? { mentioned: true } : {}),
+    };
+}
+/**
+ * SDK 解析后的消息段（text/at/face/image/video/audio/file/reply）→ canonical Segment[]。
+ * 附件段的 url 已由 SDK 归一（补 https:// 前缀）；mime 无法从载荷得知时按类型给默认。
+ */
+function extractCanonicalSegments(message) {
+    if (!Array.isArray(message))
+        return [];
+    const out = [];
+    for (const seg of message) {
+        if (!seg || typeof seg !== 'object')
+            continue;
+        const item = seg;
+        const type = item.type ?? '';
+        const data = item.data ?? {};
+        switch (type) {
+            case 'text': {
+                const text = String(data.text ?? '');
+                if (text)
+                    out.push({ type: 'text', data: { text } });
+                break;
+            }
+            case 'at': {
+                const target = String(data.user_id ?? data.id ?? '');
+                if (!target)
+                    break;
+                const name = typeof data.username === 'string' && data.username
+                    ? data.username
+                    : undefined;
+                out.push({ type: 'mention', data: name ? { target, name } : { target } });
+                break;
+            }
+            case 'face': {
+                const id = data.id;
+                if (id == null)
+                    break;
+                out.push({ type: 'face', data: { id: id } });
+                break;
+            }
+            case 'image':
+            case 'video':
+            case 'audio':
+            case 'file': {
+                const url = typeof data.url === 'string' ? data.url : '';
+                if (!url)
+                    break;
+                const media = {
+                    kind: 'url',
+                    value: url,
+                    mime_type: defaultMimeForSegment(type),
+                    ...(typeof data.name === 'string' && data.name ? { file_name: data.name } : {}),
+                    ...(typeof data.size === 'number' ? { size: data.size } : {}),
+                };
+                if (type === 'image')
+                    out.push({ type: 'image', data: { media } });
+                else if (type === 'video')
+                    out.push({ type: 'video', data: { media } });
+                else if (type === 'audio')
+                    out.push({ type: 'audio', data: { media } });
+                else
+                    out.push({ type: 'file', data: { media, ...(media.file_name ? { name: media.file_name } : {}) } });
+                break;
+            }
+            case 'reply': {
+                const messageId = String(data.id ?? data.message_id ?? '');
+                if (messageId)
+                    out.push({ type: 'reply', data: { message_id: messageId } });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return out;
+}
+function defaultMimeForSegment(type) {
+    switch (type) {
+        case 'image': return 'image/jpeg';
+        case 'video': return 'video/mp4';
+        case 'audio': return 'audio/mpeg';
+        default: return undefined;
+    }
+}
+function extractTextContent(message) {
+    if (typeof message === 'string')
+        return message;
+    if (!Array.isArray(message))
+        return '';
+    return message
+        .map((seg) => {
+        if (!seg || typeof seg !== 'object')
+            return '';
+        const item = seg;
+        if (item.type === 'text')
+            return String(item.data?.text ?? item.text ?? '');
+        return '';
+    })
+        .join('');
+}
+export function defaultCreateBot(config) {
+    const bot = new Bot({
+        appid: config.appid,
+        secret: config.secret,
+        mode: ReceiverMode.WEBSOCKET,
+        sandbox: config.sandbox,
+        dataDir: path.join(process.cwd(), 'data', 'qq'),
+        // 关闭 qq-official-bot 内置 log4js，入/出站由 getAdapterLogger('qq', …) 统一格式
+        logLevel: 'off',
+        ...(config.intents ? { intents: config.intents } : {}),
+        ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
+        ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),
+    });
+    return {
+        api: bot,
+        start: () => bot.start().then(() => undefined),
+        stop: () => stopQqOfficialBot(bot),
+        on: (event, listener) => {
+            bot.on(event, listener);
+        },
+        removeAllListeners: () => {
+            bot.removeAllListeners(undefined);
+        },
+        sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message),
+        sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message),
+        sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message),
+        sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message),
+        recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
+        recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
+        recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),
+        recallDirectMessage: (guildId, messageId) => bot.recallDirectMessage(guildId, messageId),
+        getGuilds: () => bot.guildService.getList(),
+        getChannels: (guildId) => bot.channelService.getList(guildId),
+        getChannelInfo: (channelId) => bot.channelService.getInfo(channelId),
+        getGuildMember: (guildId, userId) => bot.memberService.getGuildMemberInfo(guildId, userId),
+        getGuildRoles: (guildId) => bot.guildService.getRoles(guildId),
+        createGuildRole: (guildId, name, color) => bot.guildService.createRole(guildId, { name, color: color || 0, hoist: 0 }),
+        addMemberRole: async (guildId, channelId, userId, roleId) => {
+            await bot.memberService.addMemberRole(guildId, channelId, userId, roleId);
+            return true;
+        },
+        removeMemberRole: async (guildId, channelId, userId, roleId) => {
+            await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
+            return true;
+        },
+        approveGroupJoinRequest: (groupId, userId, options) => bot
+            .approveGroupJoinRequest?.(groupId, userId, options)
+            ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
+    };
+}

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,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "1.0.84",
-  "description": "Zhin.js adapter for QQ Official Bot",
+  "version": "1.1.0",
+  "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -34,53 +34,94 @@
     "directory": "plugins/adapters/qq"
   },
   "dependencies": {
-    "qq-official-bot": "^1.1.2"
-  },
-  "devDependencies": {
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "lucide-react": "^1.16.0",
-    "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.77",
-    "@zhin.js/console": "2.0.24",
-    "zhin.js": "1.0.81"
+    "qq-official-bot": "^1.3.0",
+    "@zhin.js/adapter": "1.1.12",
+    "@zhin.js/core": "1.1.35",
+    "@zhin.js/feature-kit": "1.1.0",
+    "@zhin.js/host-http": "1.1.0",
+    "@zhin.js/im-contract": "1.1.0",
+    "@zhin.js/logger": "1.1.0",
+    "@zhin.js/permission": "1.1.0"
   },
   "peerDependencies": {
-    "@zhin.js/client": "1.0.18",
-    "@zhin.js/console": "2.0.24",
-    "@zhin.js/http": "1.0.74",
-    "@zhin.js/logger": "0.1.63",
-    "zhin.js": "1.0.81"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "^1.1.12",
+    "@zhin.js/agent": "^1.1.23",
+    "@zhin.js/command": "^1.1.0",
+    "@zhin.js/core": "^1.1.35",
+    "@zhin.js/middleware": "^1.1.0",
+    "zhin.js": "^1.1.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/client": {
+    "@zhin.js/agent": {
+      "optional": true
+    },
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "@zhin.js/middleware": {
       "optional": true
     },
-    "@zhin.js/http": {
+    "zhin.js": {
       "optional": true
     },
-    "@zhin.js/console": {
+    "zod": {
       "optional": true
     }
   },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.1.23",
+    "@zhin.js/host-http": "1.1.0",
+    "zhin.js": "1.1.0"
+  },
   "files": [
+    "adapters",
+    "commands",
+    "middlewares",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "plugin.yml",
+    "agent",
     "README.md",
-    "node",
     "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/middleware",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib dist",
-    "build:node": "tsc"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/qq/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePlugin } from 'zhin.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',
+    metadata: {
+        displayName: 'QQ Official WebSocket Adapter',
+    },
+    setup(context) {
+        context.resources.provide(qqRuntimeStateToken, createQqRuntimeState());
+        if (context.resources.has(permissionHostToken)) {
+            const host = context.resources.use(permissionHostToken);
+            return host.registerPlatform('qq', checkQqPlatformPermit);
+        }
+    },
+});

package/schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": [
+        "websocket",
+        "webhook",
+        "middleware"
+      ],
+      "default": "websocket",
+      "description": "WebSocket gateway (default). webhook/middleware use httpHostToken POST."
+    },
+    "sandbox": {
+      "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": "框架 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"
+    },
+    "gatewayUrl": {
+      "type": "string"
+    },
+    "webhookPath": {
+      "type": "string",
+      "default": "/qq/webhook",
+      "description": "POST path on httpHostToken for webhook/middleware modes."
+    },
+    "port": {
+      "type": "number",
+      "description": "Legacy standalone webhook port (unused with httpHostToken)."
+    },
+    "path": {
+      "type": "string",
+      "description": "Legacy standalone webhook path (unused with httpHostToken)."
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "appid": {
+            "type": "string",
+            "description": "QQ official bot app ID"
+          },
+          "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": [
+          "id",
+          "appid",
+          "secret"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,16 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+import type { QqInboundMessage } from './protocol.js';
+import type { QqBotTransport } from './ws.js';
+
+export type QqClientEventMap = Record<string, QqInboundMessage | unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly qq: {
+      readonly client: QqBotTransport;
+      readonly events: QqClientEventMap;
+    };
+  }
+}
+
+export const qqClient = defineEndpointClient<QqBotTransport, QqClientEventMap>('qq');