@zhin.js/adapter-qq 5.0.2 → 5.0.3

package/lib/qq-agent-deps.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent tool deps for qq.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+export interface QqAgentEndpoint {
+    getGuilds(): Promise<unknown[]>;
+    getChannels(guildId: string): Promise<unknown[]>;
+    getChannelInfo(channelId: string): Promise<unknown>;
+    getGuildMember(guildId: string, userId: string): Promise<unknown>;
+    getGuildRoles(guildId: string): Promise<unknown[]>;
+    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
+    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+}
+export interface QqAgentDeps {
+    getEndpoint: (endpointId: string) => QqAgentEndpoint;
+}
+export declare function registerQqAgentEndpoint(endpointId: string, endpoint: QqAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setQqAgentDeps(deps: QqAgentDeps | null): void;
+export declare function getQqAgentDeps(): QqAgentDeps;

package/lib/qq-agent-deps.js

@@ -0,0 +1,30 @@
+/**
+ * Agent tool deps for qq.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerQqAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setQqAgentDeps(deps) {
+    override = deps;
+}
+export function getQqAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint(endpointId) {
+            const registered = endpoints.get(endpointId);
+            if (!registered)
+                throw new Error(`Endpoint ${endpointId} 不存在`);
+            return registered;
+        },
+    };
+}

package/lib/webhook.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import type { ResolvedQqHttpConfig } from './protocol.js';
+import type { QqBotTransport } from './ws.js';
+export type QqHttpBotTransport = QqBotTransport & {
+    middleware: (ctx: unknown, next: () => Promise<void>) => Promise<unknown>;
+};
+export type CreateQqHttpBot = (config: ResolvedQqHttpConfig) => QqHttpBotTransport;
+export interface QqWebhookHandler {
+    readonly config: ResolvedQqHttpConfig;
+    getBot(): (QqHttpBotTransport & {
+        middleware?: QqHttpBotTransport['middleware'];
+    }) | null;
+}
+export declare function registerQqWebhookRoutes(http: HttpHost, handler: QqWebhookHandler): HttpRouteRegistration[];
+export declare function handleQqWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: QqWebhookHandler): Promise<void>;
+export declare function readRequestBodyText(request: IncomingMessage): Promise<string>;
+export declare function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTransport;

package/lib/webhook.js

@@ -0,0 +1,100 @@
+/**
+ * QQ HTTP webhook / middleware inbound via httpHostToken POST.
+ */
+import path from 'node:path';
+import { Bot, ReceiverMode } from 'qq-official-bot';
+import { getLogger } from '@zhin.js/logger';
+const logger = getLogger('qq');
+export function registerQqWebhookRoutes(http, handler) {
+    const webhookPath = handler.config.webhookPath;
+    return [
+        http.route('POST', webhookPath, async (request, response) => {
+            await handleQqWebhookRequest(request, response, handler);
+        }, { summary: 'QQ webhook callback', tags: ['qq'] }),
+    ];
+}
+export async function handleQqWebhookRequest(request, response, handler) {
+    const bot = handler.getBot();
+    if (!bot?.middleware) {
+        response.writeHead(503, { 'Content-Type': 'text/plain' });
+        response.end('QQ receiver not ready');
+        return;
+    }
+    try {
+        let parsedBody;
+        const raw = await readRequestBodyText(request);
+        if (raw) {
+            try {
+                parsedBody = JSON.parse(raw);
+            }
+            catch {
+                parsedBody = undefined;
+            }
+        }
+        await bot.middleware({
+            req: request,
+            res: response,
+            request: { body: parsedBody },
+        }, async () => undefined);
+    }
+    catch (error) {
+        logger.error('QQ webhook error:', error);
+        if (!response.headersSent) {
+            response.writeHead(500, { 'Content-Type': 'text/plain' });
+            response.end('Internal Server Error');
+        }
+    }
+}
+export async function readRequestBodyText(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > 1_048_576) {
+            request.destroy();
+            throw new Error('Request body exceeds 1MB');
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function defaultCreateHttpBot(config) {
+    const bot = new Bot({
+        appid: config.appid,
+        secret: config.secret,
+        mode: ReceiverMode.MIDDLEWARE,
+        platform: 'koa',
+        sandbox: config.sandbox,
+        dataDir: path.join(process.cwd(), 'data', 'qq'),
+    });
+    return {
+        start: () => bot.start().then(() => undefined),
+        stop: () => bot.stop().then(() => undefined),
+        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),
+        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;
+        },
+        middleware: (ctx, next) => bot.middleware(ctx, next),
+    };
+}

package/lib/ws.d.ts

@@ -0,0 +1,24 @@
+import type { QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
+/** Minimal bot surface used by the endpoint (real qq-official-bot or test mock). */
+export interface QqBotTransport {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    removeAllListeners(): void;
+    sendPrivateMessage(userId: string, message: string): Promise<unknown>;
+    sendGroupMessage(groupId: string, message: string): Promise<unknown>;
+    sendGuildMessage(channelId: string, message: string): Promise<unknown>;
+    sendDirectMessage?(guildId: string, message: string): Promise<unknown>;
+    getGuilds(): Promise<unknown[]>;
+    getChannels(guildId: string): Promise<unknown[]>;
+    getChannelInfo(channelId: string): Promise<unknown>;
+    getGuildMember(guildId: string, userId: string): Promise<unknown>;
+    getGuildRoles(guildId: string): Promise<unknown[]>;
+    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
+    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+}
+export type CreateQqBot = (config: ResolvedQqWebsocketConfig) => QqBotTransport;
+export declare function bindQqBotInboundEvents(bot: QqBotTransport, admitRaw: (raw: unknown) => void): void;
+export declare function normalizeQqMessage(raw: unknown): QqInboundMessage | null;
+export declare function defaultCreateBot(config: ResolvedQqWebsocketConfig): QqBotTransport;

package/lib/ws.js

@@ -0,0 +1,118 @@
+/**
+ * QQ WebSocket transport: bot factory and inbound message normalization.
+ */
+import path from 'node:path';
+import { Bot, ReceiverMode } from 'qq-official-bot';
+import { getLevel, toLog4jsLevel } from '@zhin.js/logger';
+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 = '';
+    if (msg.message_type === 'guild') {
+        channelKind = msg.sub_type === 'direct' ? 'direct' : 'channel';
+        channelId = channelKind === 'direct'
+            ? String(msg.guild_id ?? '')
+            : String(msg.channel_id ?? '');
+    }
+    else if (msg.message_type === 'group') {
+        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 rawRoles = msg.member?.roles ?? msg.sender?.roles;
+    const authorRoles = Array.isArray(rawRoles) ? rawRoles.map(String) : undefined;
+    // 群 GROUP_AT_MESSAGE_CREATE 仅 @ 机器人时下发；频道 AT 事件看 mentions[].bot
+    const mentioned = channelKind === 'group'
+        || (Array.isArray(msg.mentions) && msg.mentions.some((m) => m?.bot === true));
+    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,
+        ...(mentioned ? { mentioned: true } : {}),
+    };
+}
+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'),
+        logLevel: toLog4jsLevel(getLevel()),
+        ...(config.intents ? { intents: config.intents } : {}),
+        ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
+        ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),
+    });
+    return {
+        start: () => bot.start().then(() => undefined),
+        stop: () => bot.stop().then(() => undefined),
+        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),
+        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;
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "5.0.2",
-  "description": "Zhin.js adapter for QQ Official Bot",
+  "version": "5.0.3",
+  "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -34,59 +34,49 @@
     "directory": "plugins/adapters/qq"
   },
   "dependencies": {
-    "qq-official-bot": "^1.2.3"
-  },
-  "devDependencies": {
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "lucide-react": "^1.22.0",
-    "typescript": "^6.0.3",
-    "zod": "^4.4.3",
-    "@zhin.js/cli": "1.0.93",
-    "@zhin.js/client": "2.0.5",
-    "@zhin.js/contract": "1.0.3",
-    "@zhin.js/host-api": "2.0.5",
-    "@zhin.js/host-router": "2.0.3",
-    "@zhin.js/logger": "1.0.74",
-    "zhin.js": "4.1.2",
-    "@zhin.js/agent": "1.0.3"
+    "qq-official-bot": "^1.2.3",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.0.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/client": "2.0.5",
-    "@zhin.js/host-api": "2.0.5",
-    "@zhin.js/contract": "1.0.3",
-    "@zhin.js/host-router": "2.0.3",
-    "@zhin.js/logger": "1.0.74",
-    "zhin.js": "4.1.2",
-    "@zhin.js/agent": "1.0.3"
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/agent": "1.0.4",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/plugin-runtime": "1.0.1",
+    "zhin.js": "4.1.3"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/agent": {
-      "optional": true
-    },
-    "@zhin.js/client": {
+    "zhin.js": {
       "optional": true
     },
-    "@zhin.js/host-router": {
-      "optional": true
-    },
-    "@zhin.js/host-api": {
+    "@zhin.js/agent": {
       "optional": true
     },
     "zod": {
       "optional": true
     }
   },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.0.4",
+    "@zhin.js/host-http": "1.0.1",
+    "zhin.js": "4.1.3"
+  },
   "files": [
+    "adapters",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
     "agent",
-    "plugin.yml",
     "README.md",
-    "node",
     "CHANGELOG.md"
   ],
   "publishConfig": {
@@ -96,9 +86,23 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "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.ts

@@ -0,0 +1,13 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { registerQqPlatformPermitChecker } from './src/platform-permit.js';
+
+export default definePlugin({
+  name: 'qq',
+  metadata: {
+    displayName: 'QQ Official WebSocket Adapter',
+  },
+  setup() {
+    // 平台权限门禁：guild_owner / guild_admin / manage_roles / manage_channels（agent 工具 platformPermit）
+    return registerQqPlatformPermitChecker();
+  },
+});

package/schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "default": "qq-bot"
+    },
+    "appid": {
+      "type": "string"
+    },
+    "secret": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["websocket", "webhook", "middleware"],
+      "default": "websocket",
+      "description": "WebSocket gateway (default). webhook/middleware use httpHostToken POST."
+    },
+    "sandbox": {
+      "type": "boolean",
+      "default": false
+    },
+    "intents": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "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)."
+    }
+  },
+  "required": ["appid", "secret"]
+}