@zhin.js/adapter-qq 7.0.2 → 7.0.5

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @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
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 7.0.2
 
 ### 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.d.ts

@@ -1,7 +1,7 @@
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -26,10 +26,7 @@ export declare class QqWebsocketEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: QqInboundMessage): void;
@@ -60,10 +57,7 @@ export declare class QqHttpEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     admit(msg: QqInboundMessage): void;
     getGuilds(): Promise<unknown[]>;

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, formatInboundTarget, parseCompoundMessageId, parseSendTarget, resolveOutboundMessageId, senderDisplayName, } from './protocol.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,38 +61,33 @@ 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({ target, payload }) {
+    async send({ conversation, payload }) {
         const body = formatOutbound(payload);
-        const parsed = parseSendTarget(target);
+        const kind = qqOutboundKind(conversation);
         const bot = this.#requireBot();
         let result;
-        switch (parsed.kind) {
+        switch (kind) {
             case 'private':
-                result = await bot.sendPrivateMessage(parsed.id, body);
+                result = await bot.sendPrivateMessage(conversation.id, body);
                 break;
             case 'group':
-                result = await bot.sendGroupMessage(parsed.id, body);
+                result = await bot.sendGroupMessage(conversation.id, body);
                 break;
             case 'channel':
-                result = await bot.sendGuildMessage(parsed.id, body);
+                result = await bot.sendGuildMessage(conversation.id, body);
                 break;
             case 'direct':
                 if (!bot.sendDirectMessage)
                     throw new Error('QQ direct message not supported by transport');
-                result = await bot.sendDirectMessage(parsed.id, body);
+                result = await bot.sendDirectMessage(conversation.id, body);
                 break;
-            default:
-                throw new Error(`unsupported QQ target kind: ${String(parsed.kind)}`);
         }
-        const messageId = `${parsed.kind}-${parsed.id}:${resolveOutboundMessageId(result)}`;
-        logger.debug(formatCompact({
-            op: 'qq_send',
-            endpoint: this.#options.config.name,
-            target,
-            messageId,
-        }));
+        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) {
@@ -116,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,
         }));
@@ -127,27 +118,34 @@ export class QqWebsocketEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        const target = formatInboundTarget(msg);
+        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({
-            adapter: this.#options.id,
-            target,
-            content: formatInboundContent(msg),
+            conversation,
+            message: { conversation, id: msg.id },
+            content,
             ...(msg.segments?.length ? { segments: msg.segments } : {}),
-            sender: senderDisplayName(msg),
-            id: msg.id,
+            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,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -191,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;
@@ -200,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;
         }
     }
@@ -253,32 +248,34 @@ 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({ target, payload }) {
+    async send({ conversation, payload }) {
         const body = formatOutbound(payload);
-        const parsed = parseSendTarget(target);
+        const kind = qqOutboundKind(conversation);
         const bot = this.#requireBot();
         let result;
-        switch (parsed.kind) {
+        switch (kind) {
             case 'private':
-                result = await bot.sendPrivateMessage(parsed.id, body);
+                result = await bot.sendPrivateMessage(conversation.id, body);
                 break;
             case 'group':
-                result = await bot.sendGroupMessage(parsed.id, body);
+                result = await bot.sendGroupMessage(conversation.id, body);
                 break;
             case 'channel':
-                result = await bot.sendGuildMessage(parsed.id, body);
+                result = await bot.sendGuildMessage(conversation.id, body);
                 break;
             case 'direct':
                 if (!bot.sendDirectMessage)
                     throw new Error('QQ direct message not supported by transport');
-                result = await bot.sendDirectMessage(parsed.id, body);
+                result = await bot.sendDirectMessage(conversation.id, body);
                 break;
-            default:
-                throw new Error(`unsupported QQ target kind: ${String(parsed.kind)}`);
         }
-        return `${parsed.kind}-${parsed.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);
@@ -297,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,
         }));
@@ -307,27 +304,34 @@ export class QqHttpEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        const target = formatInboundTarget(msg);
+        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({
-            adapter: this.#options.id,
-            target,
-            content: formatInboundContent(msg),
+            conversation,
+            message: { conversation, id: msg.id },
+            content,
             ...(msg.segments?.length ? { segments: msg.segments } : {}),
-            sender: senderDisplayName(msg),
-            id: msg.id,
+            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,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/index.d.ts

@@ -1,7 +1,8 @@
-export { formatInboundContent, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, type ParsedSendTarget, type QqAdapterConfig, type QqChannelKind, type QqInboundMessage, type QqWireSegment, type ResolvedQqConfig, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig, } from './protocol.js';
+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, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, } from './protocol.js';
+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';