@zhin.js/adapter-qq 7.0.3 → 7.0.5

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @zhin.js/adapter-qq
 
+## 7.0.5
+
+### Patch Changes
+
+- 51015d6: refactor(adapters): migrate platform-permit to PermissionSubject
+
+  All adapter platform-permit checkers now accept PermissionSubject
+  (duck-typed from Message/CommandSession) instead of Message directly.
+  registerPlatformPermitChecker is replaced by host.registerPlatform in
+  the adapter plugin setup. activity-feedback service updated for new
+  PermissionHost integration.
+
+- Updated dependencies [6f9c366]
+- Updated dependencies [373a56b]
+- Updated dependencies [0de46a8]
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [b08f7fe]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [a9fa72e]
+- Updated dependencies [c8de3ef]
+- Updated dependencies [60f0fc8]
+- Updated dependencies [574c990]
+- Updated dependencies [d096f16]
+- Updated dependencies [3f29623]
+- Updated dependencies [2916852]
+- Updated dependencies [d047869]
+- Updated dependencies [162fa34]
+- Updated dependencies [e62561e]
+- Updated dependencies [3eeeb46]
+- Updated dependencies [85d0f82]
+- Updated dependencies [61bfc1c]
+- Updated dependencies [04bad47]
+- Updated dependencies [e40b048]
+- Updated dependencies [5a5b1bb]
+- Updated dependencies [f1708c3]
+- Updated dependencies [d254a81]
+- Updated dependencies [7123c47]
+- Updated dependencies [05befc1]
+- Updated dependencies [0663b6a]
+- Updated dependencies [f28f9b3]
+- Updated dependencies [9f340f7]
+- Updated dependencies [e53444f]
+- Updated dependencies [5eedd26]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [f919b6f]
+- Updated dependencies [098e411]
+- Updated dependencies [e1b7c01]
+- Updated dependencies [9b94f87]
+- Updated dependencies [a7df753]
+  - @zhin.js/agent@1.1.5
+  - @zhin.js/host-http@1.0.8
+  - @zhin.js/permission@1.0.1
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+  - @zhin.js/middleware@1.0.8
+
+## 7.0.4
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/host-http@1.0.7
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/agent@1.1.4
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
 ## 7.0.3
 
 ### Patch Changes

package/README.md

@@ -6,7 +6,7 @@ Zhin.js QQ 官方机器人适配器（Plugin Runtime），默认通过 **WebSock
 
 - WebSocket Gateway 入站（默认；无需公网 HTTPS / host）
 - 解析私聊 / 群 / 频道消息
-- 出站 `send({ target, payload })` → QQ API（`private:` / `group:` / `channel:` / `direct:`）
+- 出站 `send({ conversation, payload })` → QQ API（`conversation.kind`/`id`/`parent` 结构化寻址）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - Webhook / middleware 模式已实现（经 `httpHostToken` 注册 POST 路由）
 - AI `@` 触发标注：群消息（GROUP_AT_MESSAGE_CREATE 仅 @ 时下发）与频道 `mentions[].bot` 会在入站 metadata 标 `mentioned: true`（新 Plugin Runtime 纯文本 content 经 metadata 传递 @）
@@ -25,8 +25,8 @@ pnpm add @zhin.js/adapter-qq
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 - **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（WebSocket 路径）
 
-入站：`gateway.receive({ adapter, target: 'group:…'|…, content, sender, metadata })`  
-出站：`send({ target, payload })` → `sendPrivateMessage` / `sendGroupMessage` / `sendGuildMessage`
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（ConversationRef 结构化寻址）  
+出站：`send({ conversation, payload })` → `sendPrivateMessage` / `sendGroupMessage` / `sendGuildMessage`
 
 ## 前置条件
 
@@ -49,22 +49,49 @@ plugins:
       - name: my-qq-bot
         appid: ${QQ_APPID}
         secret: ${QQ_SECRET}
+        # botKind / intents 可由向导写入；`qq.endpoint add` 扫码后会追问公域/私域再写入
 ```
 
+### botKind 与 intents
+
+WebSocket Identify 的 `intents` **必须与开放平台已开通的权限一致**，否则会断连。
+群聊无公/私域之分，两类都订阅 `GROUP_AND_C2C_EVENT`；差异只在频道消息 intent：
+
+| `botKind` | 频道消息 intent | 共用 intents |
+|-----------|-----------------|--------------|
+| `public`（默认，公域） | `PUBLIC_GUILD_MESSAGES`（仅 @） | `GROUP_AND_C2C_EVENT`, `GUILDS`, `GUILD_MEMBERS`, `DIRECT_MESSAGE` |
+| `private`（私域） | `GUILD_MESSAGES`（频道全量） | 同上 |
+
+公域机器人订阅 `GUILD_MESSAGES` 会 Identify 失败断连。显式配置 `intents` 时优先于 `botKind`。
+`create-zhin` / `zhin setup` 会询问公/私域并写入；`qq.endpoint add` 扫码成功后在同一会话追问 `public`/`private`（或 `公域`/`私域`），确认后一次性写 `.env` 与 yaml。
+
 多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
 
 ```yaml
 plugins:
   qq:
     mode: websocket
-    intents: [GUILDS, GROUP_AND_C2C_EVENT]
     endpoints:
       - name: main-bot
         appid: ${QQ_APPID}
         secret: ${QQ_SECRET}
-      - name: second-bot
+        botKind: public
+        intents:
+          - GROUP_AND_C2C_EVENT
+          - GUILDS
+          - GUILD_MEMBERS
+          - DIRECT_MESSAGE
+          - PUBLIC_GUILD_MESSAGES
+      - name: private-bot
         appid: ${QQ_APPID_2}
         secret: ${QQ_SECRET_2}
+        botKind: private
+        intents:
+          - GROUP_AND_C2C_EVENT
+          - GUILDS
+          - GUILD_MEMBERS
+          - DIRECT_MESSAGE
+          - GUILD_MESSAGES
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-qq`（`instanceKey: qq`）。
@@ -75,13 +102,13 @@ plugins:
 
 | 命令 | 说明 |
 |------|------|
-| `qq.endpoint add [name]` | 手机 QQ 扫码绑定：下发二维码链接 → 确认后凭据写入 `.env`（`QQ_<NAME>_APPID/SECRET`），并追加 `plugins.qq.endpoints`（重启生效） |
-| `qq.endpoint cancel` | 取消进行中的扫码绑定（同时只允许一个流程） |
+| `qq.endpoint add [name]` | 手机 QQ 扫码绑定 → **追问公域/私域** → 一次性写入 `.env` + `plugins.qq.endpoints`（重启生效） |
+| `qq.endpoint cancel` | 取消进行中的扫码绑定或待确认的公域/私域选择 |
 | `qq.endpoint list` | 列出运行中与配置中的 endpoints |
 | `qq.endpoint remove <name>` | 从配置移除 endpoint（`.env` 键保留，可手动清理） |
 
-add/cancel/remove 受 `master` 限制：实例配置声明了 `master`（顶层或 `endpoints[i]`）时仅
-master 可执行；未配置则放行（首个扫码绑定者即 owner）。二维码当前以链接文本下发
+add/cancel/remove 受 `master` 限制：实例配置声明了 `master`（顶层或 `endpoints[i].master`）时仅
+master 可执行；未配置则放行（首个扫码绑定者会写入该 endpoint 的 `master`）。二维码当前以链接文本下发
 （出站富媒体待迁移），用手机 QQ 打开链接即可扫码。
 
 ## 环境变量

package/adapters/qq.js

@@ -22,26 +22,28 @@ export default defineAdapter({
         const gateway = context.use(messageGatewayToken);
         // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
         const state = context.use(qqRuntimeStateToken);
-        state.endpoints.set(config.name, {
-            name: config.name,
+        state.endpoints.set(config.id, {
+            id: config.id,
             mode: config.mode,
         });
-        const endpoint = (config.mode === 'webhook' || config.mode === 'middleware')
-            ? new QqHttpEndpoint({
+        // 正向判 websocket：TS 对 `mode === 'webhook' || mode === 'middleware'` 的
+        // 否定分支不做联合消减（多字面量判别式），反向写会让 config 窄化失败。
+        const endpoint = config.mode === 'websocket'
+            ? new QqWebsocketEndpoint({
                 id: context.id,
                 gateway,
-                http: context.use(httpHostToken),
                 config,
             })
-            : new QqWebsocketEndpoint({
+            : new QqHttpEndpoint({
                 id: context.id,
                 gateway,
+                http: context.use(httpHostToken),
                 config,
             });
         // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq.endpoint list 仍显示运行中。
         const stopEndpoint = endpoint.stop.bind(endpoint);
         endpoint.stop = async () => {
-            state.endpoints.delete(config.name);
+            state.endpoints.delete(config.id);
             await stopEndpoint();
         };
         return endpoint;

package/adapters/qq.ts

@@ -37,26 +37,28 @@ export default defineAdapter<QqAdapterConfig>({
     const gateway = context.use(messageGatewayToken);
     // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
     const state = context.use(qqRuntimeStateToken);
-    state.endpoints.set(config.name, {
-      name: config.name,
+    state.endpoints.set(config.id, {
+      id: config.id,
       mode: config.mode,
     });
-    const endpoint = (config.mode === 'webhook' || config.mode === 'middleware')
-      ? new QqHttpEndpoint({
+    // 正向判 websocket：TS 对 `mode === 'webhook' || mode === 'middleware'` 的
+    // 否定分支不做联合消减（多字面量判别式），反向写会让 config 窄化失败。
+    const endpoint = config.mode === 'websocket'
+      ? new QqWebsocketEndpoint({
         id: context.id,
         gateway,
-        http: context.use(httpHostToken),
         config,
       })
-      : new QqWebsocketEndpoint({
+      : new QqHttpEndpoint({
         id: context.id,
         gateway,
+        http: context.use(httpHostToken),
         config,
       });
     // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq.endpoint list 仍显示运行中。
     const stopEndpoint = endpoint.stop.bind(endpoint);
     endpoint.stop = async () => {
-      state.endpoints.delete(config.name);
+      state.endpoints.delete(config.id);
       await stopEndpoint();
     };
     return endpoint;

package/commands/endpoint/cancel.js

@@ -3,7 +3,7 @@ import { defineCommand } from '@zhin.js/command';
 import { isQqEndpointOperator, QQ_ENDPOINT_FORBIDDEN, runQqEndpointCancel, } from "../../lib/qq-endpoint-commands.js";
 import { qqRuntimeStateToken } from "../../lib/qq-runtime-state.js";
 export default defineCommand({
-    description: '取消进行中的 QQ 扫码绑定流程',
+    description: '取消进行中的 QQ 扫码绑定或公域/私域选择',
     execute({ config, input, use }) {
         if (!isQqEndpointOperator(config, input))
             return QQ_ENDPOINT_FORBIDDEN;

package/commands/endpoint/cancel.ts

@@ -7,7 +7,7 @@ import {
 import { qqRuntimeStateToken } from '../../src/qq-runtime-state.js';
 
 export default defineCommand({
-  description: '取消进行中的 QQ 扫码绑定流程',
+  description: '取消进行中的 QQ 扫码绑定或公域/私域选择',
   execute({ config, input, use }) {
     if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
     return runQqEndpointCancel(use(qqRuntimeStateToken));

package/lib/endpoint.js

@@ -1,11 +1,11 @@
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { formatOutbound } from './outbound.js';
 import { registerQqAgentEndpoint } from './qq-agent-deps.js';
 import { formatInboundContent, parseCompoundMessageId, qqInboundConversation, qqOutboundKind, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
 import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
 import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
-const logger = getLogger('qq');
 export class QqWebsocketEndpoint {
+    #logger;
     #options;
     #createBot;
     #bot = null;
@@ -14,32 +14,28 @@ export class QqWebsocketEndpoint {
     #unregisterAgent;
     management = createQqEndpointManagement(this);
     constructor(options) {
+        this.#logger = getAdapterLogger('qq', options.config.id);
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateBot;
     }
     /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
     get name() {
-        return this.#options.config.name;
+        return this.#options.config.id;
     }
     async start() {
         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}）`, { cause: error });
         }
@@ -65,7 +61,7 @@ export class QqWebsocketEndpoint {
             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 }) {
         const body = formatOutbound(payload);
@@ -89,12 +85,9 @@ export class QqWebsocketEndpoint {
                 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;
     }
     async recallMessage(messageId) {
@@ -114,9 +107,9 @@ export class QqWebsocketEndpoint {
                 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,
         }));
@@ -126,23 +119,31 @@ export class QqWebsocketEndpoint {
         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),
@@ -188,6 +189,7 @@ export class QqWebsocketEndpoint {
 }
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
 export class QqHttpEndpoint {
+    #logger;
     #options;
     #createBot;
     #bot = null;
@@ -197,33 +199,29 @@ export class QqHttpEndpoint {
     #unregisterAgent;
     management = createQqEndpointManagement(this);
     constructor(options) {
+        this.#logger = getAdapterLogger('qq', options.config.id);
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateHttpBot;
     }
     /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
     get name() {
-        return this.#options.config.name;
+        return this.#options.config.id;
     }
     async start() {
         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.#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;
         }
     }
@@ -250,7 +248,7 @@ export class QqHttpEndpoint {
             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 }) {
         const body = formatOutbound(payload);
@@ -273,7 +271,11 @@ export class QqHttpEndpoint {
                 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) {
         const { kind, channelId, qqMsgId } = parseCompoundMessageId(messageId);
@@ -292,9 +294,9 @@ export class QqHttpEndpoint {
                 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,
         }));
@@ -303,23 +305,31 @@ export class QqHttpEndpoint {
         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/lib/index.d.ts

@@ -1,7 +1,8 @@
 export { formatInboundContent, formatOutboundText, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, type QqAdapterConfig, type QqChannelKind, type QqInboundMessage, type QqWireSegment, type ResolvedQqConfig, type ResolvedQqHttpConfig, 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, type QqOutboundElem, type QqOutboundMessage, } from './outbound.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, type CreateQqBot, type CreateQqHttpBot, type QqBotTransport, type QqEndpointOptions, type QqHttpBotTransport, type QqHttpEndpointOptions, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, type QqWebhookHandler, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
 export { getQqAgentDeps, registerQqAgentEndpoint, setQqAgentDeps, type QqAgentDeps, type QqAgentEndpoint, } from './qq-agent-deps.js';
-export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, registerQqPlatformPermitChecker, } from './platform-permit.js';
+export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';

package/lib/index.js

@@ -1,7 +1,8 @@
 export { formatInboundContent, formatOutboundText, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, } from './protocol.js';
+export { DEFAULT_QQ_BOT_KIND, QQ_INTENTS_BY_KIND, defaultQqEndpointIntentFields, parseQqBotKind, resolveQqIntents, } from './qq-intents.js';
 export { formatOutbound, resolveMediaFile, } from './outbound.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
 export { getQqAgentDeps, registerQqAgentEndpoint, setQqAgentDeps, } from './qq-agent-deps.js';
-export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, registerQqPlatformPermitChecker, } from './platform-permit.js';
+export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';

package/lib/platform-permit.d.ts

@@ -1,7 +1,7 @@
 /**
  * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
  */
-import { type Message } from '@zhin.js/core';
+import type { PermissionSubject } from '@zhin.js/permission';
 export declare function platformPermit(perm: string): string;
 export declare function qqGuildPermitResolver(logicalPerm: string): string;
 export declare function normalizeQqGuildSenderForPermit(input: {
@@ -12,5 +12,4 @@ export declare function normalizeQqGuildSenderForPermit(input: {
     role?: string;
     permissions?: string[];
 };
-export declare function checkQqPlatformPermit(perm: string, message: Message<any>): boolean;
-export declare function registerQqPlatformPermitChecker(): () => void;
+export declare function checkQqPlatformPermit(perm: string, subject: PermissionSubject): boolean;

package/lib/platform-permit.js

@@ -1,7 +1,3 @@
-/**
- * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
- */
-import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'qq';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -26,10 +22,9 @@ export function normalizeQqGuildSenderForPermit(input) {
     }
     return { role: 'member', permissions };
 }
-export function checkQqPlatformPermit(perm, message) {
-    const sender = message.$sender;
-    const permissions = sender.permissions ?? [];
-    const role = sender.role;
+export function checkQqPlatformPermit(perm, subject) {
+    const role = subject.sender?.role?.[0];
+    const permissions = subject.sender?.permissions ?? [];
     const has = (t) => permissions.includes(t);
     switch (perm) {
         case 'guild_owner':
@@ -44,6 +39,3 @@ export function checkQqPlatformPermit(perm, message) {
             return false;
     }
 }
-export function registerQqPlatformPermitChecker() {
-    return registerPlatformPermitChecker(ADAPTER, checkQqPlatformPermit);
-}

package/lib/protocol.d.ts

@@ -5,13 +5,16 @@
 import type { ConversationRef } from '@zhin.js/im-contract';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface QqAdapterConfig {
-    readonly name?: string;
+    readonly id?: string;
     readonly appid?: string;
     readonly secret?: string;
     /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
     readonly mode?: 'websocket' | 'webhook' | 'middleware';
     readonly sandbox?: boolean;
+    /** Explicit intents; when omitted, derived from `botKind` (default public). */
     readonly intents?: readonly string[];
+    /** public | private — drives default intents when `intents` omitted. */
+    readonly botKind?: string;
     readonly accessTokenUrl?: string;
     readonly gatewayUrl?: string;
     readonly webhookPath?: string;
@@ -20,12 +23,13 @@ export interface QqAdapterConfig {
     /** Transitional: legacy root `endpoints[]` with `context: qq`. */
     readonly endpoints?: ReadonlyArray<{
         readonly context?: string;
-        readonly name?: string;
+        readonly id?: string;
         readonly appid?: string;
         readonly secret?: string;
         readonly mode?: 'websocket' | 'webhook' | 'middleware';
         readonly sandbox?: boolean;
         readonly intents?: readonly string[];
+        readonly botKind?: string;
         readonly accessTokenUrl?: string;
         readonly gatewayUrl?: string;
         readonly webhookPath?: string;
@@ -36,7 +40,7 @@ export interface QqAdapterConfig {
 export interface ResolvedQqWebsocketConfig {
     readonly context: 'qq';
     readonly mode: 'websocket';
-    readonly name: string;
+    readonly id: string;
     readonly appid: string;
     readonly secret: string;
     readonly sandbox: boolean;
@@ -47,7 +51,7 @@ export interface ResolvedQqWebsocketConfig {
 export interface ResolvedQqHttpConfig {
     readonly context: 'qq';
     readonly mode: 'webhook' | 'middleware';
-    readonly name: string;
+    readonly id: string;
     readonly appid: string;
     readonly secret: string;
     readonly webhookPath: string;
@@ -85,7 +89,7 @@ export declare function resolveQqConfig(config?: QqAdapterConfig): ResolvedQqCon
  * 入站归一化 → ConversationRef：`direct`（频道私信）映射为 guild 容器内的
  * private 会话；频道消息的所属 guild 进 `parent`。
  */
-export declare function qqInboundConversation(endpointId: string, msg: QqInboundMessage): ConversationRef;
+export declare function qqInboundConversation(endpointKey: string, msg: QqInboundMessage): ConversationRef;
 /** 出站：guild 容器内的 private 会话即 QQ `direct`（频道私信）。 */
 export declare function qqOutboundKind(conversation: ConversationRef): QqChannelKind;
 export declare function senderDisplayName(msg: QqInboundMessage): string;