@zhin.js/adapter-qq 7.0.2 → 7.0.5

package/lib/qq-intents.js

@@ -0,0 +1,50 @@
+/**
+ * QQ 官方机器人 intents 与公域/私域映射。
+ *
+ * 群聊无公/私域之分，两类都订阅 `GROUP_AND_C2C_EVENT`。
+ * 频道消息 intent 不同：
+ * - public（公域）：`PUBLIC_GUILD_MESSAGES`（仅 @ 机器人）
+ * - private（私域）：`GUILD_MESSAGES`（频道全量消息；公域订阅会 Identify 失败）
+ */
+/** 扫码绑定 / 未声明 botKind 时的默认（公域更常见）。 */
+export const DEFAULT_QQ_BOT_KIND = 'public';
+/** 公/私域共用：群@+私聊 C2C、频道基础事件、频道私信。 */
+const QQ_SHARED_INTENTS = Object.freeze([
+    'GROUP_AND_C2C_EVENT',
+    'GUILDS',
+    'GUILD_MEMBERS',
+    'DIRECT_MESSAGE',
+]);
+export const QQ_INTENTS_BY_KIND = Object.freeze({
+    public: Object.freeze([
+        ...QQ_SHARED_INTENTS,
+        'PUBLIC_GUILD_MESSAGES',
+    ]),
+    private: Object.freeze([
+        ...QQ_SHARED_INTENTS,
+        'GUILD_MESSAGES',
+    ]),
+});
+/** 解析 botKind：仅接受 `public` / `private`。 */
+export function parseQqBotKind(value) {
+    if (value === 'public' || value === 'private')
+        return value;
+    return undefined;
+}
+/**
+ * 解析最终 intents：显式 `intents` 优先；否则按 `botKind`（默认 public）展开。
+ */
+export function resolveQqIntents(input) {
+    if (Array.isArray(input.intents) && input.intents.length > 0) {
+        return Object.freeze(input.intents.map(String));
+    }
+    const kind = parseQqBotKind(input.botKind) ?? DEFAULT_QQ_BOT_KIND;
+    return QQ_INTENTS_BY_KIND[kind];
+}
+/** 添加 endpoint 时写入配置的默认字段（显式展开，便于用户改）。 */
+export function defaultQqEndpointIntentFields(botKind = DEFAULT_QQ_BOT_KIND) {
+    return Object.freeze({
+        botKind,
+        intents: QQ_INTENTS_BY_KIND[botKind],
+    });
+}

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

@@ -1,17 +1,30 @@
 export interface QqRunningEndpoint {
-    name: string;
+    id: string;
     mode: string;
 }
 export interface QqBindFlowHandle {
-    /** 绑定期望的 endpoint 名（未指定时为 undefined，成功后取 appId） */
-    name?: string;
+    /** 绑定期望的 endpoint id（未指定时为 undefined，成功后取 appId） */
+    id?: string;
     stop: () => void;
 }
+/**
+ * 扫码成功后暂存在内存：确认公域/私域后再一次性写 .env + yaml。
+ * （提前写 .env 会触发 HMR，冲掉 pending。）
+ */
+export interface QqPendingBotKind {
+    readonly endpointId: string;
+    readonly appId: string;
+    readonly appSecret: string;
+    /** 发起 add 的会话键；仅同会话回复可完成选择 */
+    readonly sessionKey: string;
+}
 export interface QqRuntimeState {
-    /** 当前 generation 已成功创建的 endpoint（name → 描述） */
+    /** 当前 generation 已成功创建的 endpoint（id → 描述） */
     readonly endpoints: Map<string, QqRunningEndpoint>;
     /** 全局单例：同一时间只允许一个扫码绑定流程 */
     bindFlow: QqBindFlowHandle | null;
+    /** 扫码完成后等待 botKind 选择（凭据仅在内存） */
+    pendingBotKind: QqPendingBotKind | null;
 }
 export declare function createQqRuntimeState(): QqRuntimeState;
 export declare const qqRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<QqRuntimeState>;

package/lib/qq-runtime-state.js

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

package/lib/webhook.js

@@ -60,6 +60,8 @@ export function defaultCreateHttpBot(config) {
         platform: 'koa',
         sandbox: config.sandbox,
         dataDir: path.join(process.cwd(), 'data', 'qq'),
+        // 关闭内置 log4js，与 WebSocket 模式一致走 zhin adapter logger
+        logLevel: 'off',
     });
     return {
         start: () => bot.start().then(() => undefined),

package/lib/ws.js

@@ -3,7 +3,6 @@
  */
 import path from 'node:path';
 import { Bot, ReceiverMode } from 'qq-official-bot';
-import { getLevel, toLog4jsLevel } from '@zhin.js/logger';
 /**
  * qq-official-bot 1.2.x keeps a second `userClose` flag in Connection.
  * Session.stop() does not update it, so a normal shutdown is treated as an
@@ -190,7 +189,8 @@ export function defaultCreateBot(config) {
         mode: ReceiverMode.WEBSOCKET,
         sandbox: config.sandbox,
         dataDir: path.join(process.cwd(), 'data', 'qq'),
-        logLevel: toLog4jsLevel(getLevel()),
+        // 关闭 qq-official-bot 内置 log4js，入/出站由 getAdapterLogger('qq', …) 统一格式
+        logLevel: 'off',
         ...(config.intents ? { intents: config.intents } : {}),
         ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
         ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),

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.2",
+  "version": "7.0.5",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,20 +35,23 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@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.4",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@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": {
@@ -66,13 +69,14 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/host-http": "1.0.5",
-    "zhin.js": "6.0.1"
+    "@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",
@@ -102,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"
         ]