@zhin.js/adapter-qq 5.0.2 → 6.0.0

package/lib/qq-endpoint-config.js

@@ -0,0 +1,110 @@
+/**
+ * zhin.config.yml 中 plugins.qq.endpoints 的读写（Plugin Runtime 版）。
+ * 用 yaml Document 操作以保留现有注释；仅支持 .yml/.yaml，其它格式报错提示手动处理。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMap, isSeq, parseDocument } from 'yaml';
+import { resolveProjectRoot } from './qq-bind-persist.js';
+const CONFIG_BASENAME = 'zhin.config';
+const YAML_EXTENSIONS = ['.yml', '.yaml'];
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export function findQqConfigFile(projectRoot) {
+    const root = projectRoot ?? resolveProjectRoot();
+    const envConfig = process.env.ZHIN_CONFIG?.trim();
+    if (envConfig)
+        return path.resolve(root, envConfig);
+    for (const ext of YAML_EXTENSIONS) {
+        const candidate = path.join(root, `${CONFIG_BASENAME}${ext}`);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    for (const ext of ['.json', '.toml', '.ts']) {
+        const candidate = path.join(root, `${CONFIG_BASENAME}${ext}`);
+        if (fs.existsSync(candidate)) {
+            throw new Error(`暂不支持写入 ${ext} 配置文件，请手动在 ${CONFIG_BASENAME}${ext} 的 plugins.qq.endpoints 中维护`);
+        }
+    }
+    return path.join(root, `${CONFIG_BASENAME}.yml`);
+}
+function readConfigDocument(projectRoot) {
+    const filePath = findQqConfigFile(projectRoot);
+    const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : '';
+    const doc = parseDocument(content || '{}');
+    return { filePath, doc };
+}
+function writeConfigDocument({ filePath, doc }) {
+    fs.writeFileSync(filePath, doc.toString());
+}
+/** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
+export function listQqEndpointEntries(projectRoot) {
+    const { doc } = readConfigDocument(projectRoot);
+    const plugins = doc.toJS()?.plugins;
+    if (!plugins || typeof plugins !== 'object' || Array.isArray(plugins))
+        return [];
+    const endpoints = plugins.qq?.endpoints;
+    if (!Array.isArray(endpoints))
+        return [];
+    return endpoints.filter((entry) => !!entry && typeof entry === 'object' && typeof entry.name === 'string');
+}
+function entryName(item) {
+    if (!isMap(item))
+        return undefined;
+    const name = item.get('name');
+    return typeof name === 'string' && name ? name : undefined;
+}
+/**
+ * 确保 plugins.qq.endpoints 存在并返回其 YAMLSeq（节点级操作，保留既有条目与注释）。
+ * `plugins: []`（legacy 空列表，Runtime 忽略）可直接替换为 map；非空数组拒绝写入。
+ */
+function ensureEndpointsSeq(doc) {
+    const plugins = doc.get('plugins');
+    if (isSeq(plugins) && plugins.items.length > 0) {
+        throw new Error('配置的 plugins 是数组形态（legacy 插件名列表），请手动迁移为 map 后再试');
+    }
+    if (plugins !== undefined && !isMap(plugins) && !isSeq(plugins)) {
+        throw new Error('配置的 plugins 字段形态异常，请手动检查 zhin.config.yml');
+    }
+    if (!isMap(doc.get('plugins'))) {
+        // 注意：空对象 {} 不会被 doc.set 自动包装为 YAMLMap，必须显式 createNode
+        doc.set('plugins', doc.createNode({}));
+    }
+    const qq = doc.getIn(['plugins', 'qq']);
+    if (qq !== undefined && !isMap(qq)) {
+        throw new Error('配置的 plugins.qq 字段形态异常，请手动检查 zhin.config.yml');
+    }
+    if (!isMap(doc.getIn(['plugins', 'qq']))) {
+        doc.setIn(['plugins', 'qq'], doc.createNode({}));
+    }
+    const endpoints = doc.getIn(['plugins', 'qq', 'endpoints']);
+    if (endpoints !== undefined && !isSeq(endpoints)) {
+        throw new Error('配置的 plugins.qq.endpoints 字段形态异常，请手动检查 zhin.config.yml');
+    }
+    if (!isSeq(doc.getIn(['plugins', 'qq', 'endpoints']))) {
+        doc.setIn(['plugins', 'qq', 'endpoints'], doc.createNode([]));
+    }
+    return doc.getIn(['plugins', 'qq', 'endpoints']);
+}
+/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+export function addQqEndpointToConfig(entry, projectRoot) {
+    const document = readConfigDocument(projectRoot);
+    const seq = ensureEndpointsSeq(document.doc);
+    if (seq.items.some((item) => entryName(item) === entry.name)) {
+        throw new Error(`配置中已存在 qq endpoint「${entry.name}」，可先 qq endpoint remove ${entry.name} 再重新添加`);
+    }
+    seq.items.push(document.doc.createNode(entry));
+    writeConfigDocument(document);
+    return document.filePath;
+}
+/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
+export function removeQqEndpointFromConfig(name, projectRoot) {
+    const document = readConfigDocument(projectRoot);
+    const seq = ensureEndpointsSeq(document.doc);
+    const next = seq.items.filter((item) => entryName(item) !== name);
+    if (next.length === seq.items.length) {
+        return { removed: false, filePath: document.filePath };
+    }
+    seq.items = next;
+    writeConfigDocument(document);
+    return { removed: true, filePath: document.filePath };
+}

package/lib/qq-runtime-state.d.ts

@@ -0,0 +1,17 @@
+export interface QqRunningEndpoint {
+    name: string;
+    mode: string;
+}
+export interface QqBindFlowHandle {
+    /** 绑定期望的 endpoint 名（未指定时为 undefined，成功后取 appId） */
+    name?: string;
+    stop: () => void;
+}
+export interface QqRuntimeState {
+    /** 当前 generation 已成功创建的 endpoint（name → 描述） */
+    readonly endpoints: Map<string, QqRunningEndpoint>;
+    /** 全局单例：同一时间只允许一个扫码绑定流程 */
+    bindFlow: QqBindFlowHandle | null;
+}
+export declare function createQqRuntimeState(): QqRuntimeState;
+export declare const qqRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<QqRuntimeState>;

package/lib/qq-runtime-state.js

@@ -0,0 +1,13 @@
+/**
+ * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
+ * 扫码绑定流程的全局单例。由 plugin.ts setup() provide，
+ * adapter create 与 commands 通过 use(qqRuntimeStateToken) 共享（同一 owner generation）。
+ */
+import { createToken } from '@zhin.js/plugin-runtime';
+export function createQqRuntimeState() {
+    return {
+        endpoints: new Map(),
+        bindFlow: null,
+    };
+}
+export const qqRuntimeStateToken = createToken('zhin.qq.runtime-state', 'QQ adapter runtime state (running endpoints + bind flow singleton)');

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": "6.0.0",
+  "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,52 @@
     "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",
+    "yaml": "^2.9.0",
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.1.0",
+    "@zhin.js/command": "1.0.2"
   },
   "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.1.0",
+    "@zhin.js/agent": "1.0.5",
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/plugin-runtime": "1.1.0",
+    "zhin.js": "5.0.0"
   },
   "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.5",
+    "@zhin.js/host-http": "1.0.2",
+    "zhin.js": "5.0.0"
+  },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
     "agent",
-    "plugin.yml",
     "README.md",
-    "node",
     "CHANGELOG.md"
   ],
   "publishConfig": {
@@ -96,9 +89,27 @@
   "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"
+      },
+      {
+        "package": "@zhin.js/command",
+        "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,16 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { registerQqPlatformPermitChecker } from './src/platform-permit.js';
+import { createQqRuntimeState, qqRuntimeStateToken } from './src/qq-runtime-state.js';
+
+export default definePlugin({
+  name: 'qq',
+  metadata: {
+    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();
+  },
+});

package/schema.json

@@ -0,0 +1,85 @@
+{
+  "$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
+    },
+    "master": {
+      "type": ["string", "number"],
+      "description": "Endpoint Owner（qq endpoint 管理命令权限、AI master 角色）；endpoints[i] 可逐项覆盖"
+    },
+    "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)."
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "QQ bot name"
+          },
+          "appid": {
+            "type": "string",
+            "description": "QQ official bot app ID"
+          },
+          "secret": {
+            "type": "string",
+            "description": "QQ official bot secret"
+          }
+        },
+        "required": [
+          "name",
+          "appid",
+          "secret"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}