@zhin.js/adapter-qq 7.0.1 → 7.0.3

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @zhin.js/adapter-qq
 
+## 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
+
+- Updated dependencies [696ab1b]
+  - @zhin.js/agent@1.1.2
+  - zhin.js@6.0.1
+
 ## 7.0.1
 
 ### Patch Changes

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,7 +1,7 @@
 import { formatCompact, getLogger } 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');
@@ -67,34 +67,32 @@ export class QqWebsocketEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    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)}`;
+        const messageId = `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
         logger.debug(formatCompact({
             op: 'qq_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -127,14 +125,13 @@ export class QqWebsocketEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        const target = formatInboundTarget(msg);
+        const conversation = qqInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
             ...(msg.segments?.length ? { segments: msg.segments } : {}),
             sender: senderDisplayName(msg),
-            id: msg.id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 channelKind: msg.channelKind,
@@ -147,7 +144,7 @@ export class QqWebsocketEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'qq_gateway_receive_failed',
-                target,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -255,30 +252,28 @@ export class QqHttpEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    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)}`;
+        return `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
     }
     async recallMessage(messageId) {
         const { kind, channelId, qqMsgId } = parseCompoundMessageId(messageId);
@@ -307,14 +302,13 @@ export class QqHttpEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        const target = formatInboundTarget(msg);
+        const conversation = qqInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
             ...(msg.segments?.length ? { segments: msg.segments } : {}),
             sender: senderDisplayName(msg),
-            id: msg.id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 channelKind: msg.channelKind,
@@ -327,7 +321,7 @@ export class QqHttpEndpoint {
         }).catch((err) => {
             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,4 +1,4 @@
-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 { 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';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { formatInboundContent, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, } from './protocol.js';
+export { formatInboundContent, formatOutboundText, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, } from './protocol.js';
 export { formatOutbound, resolveMediaFile, } from './outbound.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, } from './webhook.js';

package/lib/protocol.d.ts

@@ -2,6 +2,7 @@
  * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface QqAdapterConfig {
     readonly name?: string;
@@ -79,16 +80,14 @@ export interface QqWireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
 }
-export interface ParsedSendTarget {
-    readonly kind: QqChannelKind;
-    readonly id: string;
-}
 export declare function resolveQqConfig(config?: QqAdapterConfig): ResolvedQqConfig;
 /**
- * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ * 入站归一化 → ConversationRef：`direct`（频道私信）映射为 guild 容器内的
+ * private 会话；频道消息的所属 guild 进 `parent`。
  */
-export declare function formatInboundTarget(msg: QqInboundMessage): string;
-export declare function parseSendTarget(target: string): ParsedSendTarget;
+export declare function qqInboundConversation(endpointId: string, msg: QqInboundMessage): ConversationRef;
+/** 出站：guild 容器内的 private 会话即 QQ `direct`（频道私信）。 */
+export declare function qqOutboundKind(conversation: ConversationRef): QqChannelKind;
 export declare function senderDisplayName(msg: QqInboundMessage): string;
 export declare function formatInboundContent(msg: QqInboundMessage): string;
 /**

package/lib/protocol.js

@@ -43,22 +43,25 @@ export function resolveQqConfig(config = {}) {
     };
 }
 /**
- * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ * 入站归一化 → ConversationRef：`direct`（频道私信）映射为 guild 容器内的
+ * private 会话；频道消息的所属 guild 进 `parent`。
  */
-export function formatInboundTarget(msg) {
-    return `${msg.channelKind}:${msg.channelId}`;
+export function qqInboundConversation(endpointId, msg) {
+    const kind = msg.channelKind === 'direct' ? 'private' : msg.channelKind;
+    return {
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind,
+        id: msg.channelId,
+        ...(msg.guildId && (msg.channelKind === 'channel' || msg.channelKind === 'direct')
+            ? { parent: { kind: 'channel', id: msg.guildId } }
+            : {}),
+    };
 }
-export function parseSendTarget(target) {
-    const sep = target.indexOf(':');
-    if (sep <= 0) {
-        return { kind: 'private', id: target };
-    }
-    const head = target.slice(0, sep);
-    const rest = target.slice(sep + 1);
-    if (head === 'private' || head === 'group' || head === 'channel' || head === 'direct') {
-        return { kind: head, id: rest };
-    }
-    return { kind: 'private', id: target };
+/** 出站：guild 容器内的 private 会话即 QQ `direct`（频道私信）。 */
+export function qqOutboundKind(conversation) {
+    if (conversation.kind === 'private' && conversation.parent?.kind === 'channel')
+        return 'direct';
+    return conversation.kind;
 }
 export function senderDisplayName(msg) {
     return msg.authorName || msg.authorId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "7.0.1",
+  "version": "7.0.3",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,20 +35,21 @@
   },
   "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/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.1",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,9 +67,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.1",
-    "@zhin.js/host-http": "1.0.5",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/host-http": "1.0.6",
+    "zhin.js": "6.0.2"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -5,6 +5,7 @@ import type {
   EndpointChannel,
   EndpointInstance,
   EndpointManagement,
+  EndpointSendRequest,
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
@@ -14,9 +15,9 @@ import { formatOutbound } from './outbound.js';
 import { registerQqAgentEndpoint } from './qq-agent-deps.js';
 import {
   formatInboundContent,
-  formatInboundTarget,
   parseCompoundMessageId,
-  parseSendTarget,
+  qqInboundConversation,
+  qqOutboundKind,
   resolveOutboundMessageId,
   senderDisplayName,
   type QqInboundMessage,
@@ -118,33 +119,31 @@ export class QqWebsocketEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const body = formatOutbound(payload);
-    const parsed = parseSendTarget(target);
+    const kind = qqOutboundKind(conversation);
     const bot = this.#requireBot();
     let result: unknown;
-    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 as ParsedSendTarget).kind)}`);
     }
-    const messageId = `${parsed.kind}-${parsed.id}:${resolveOutboundMessageId(result)}`;
+    const messageId = `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
     logger.debug(formatCompact({
       op: 'qq_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -178,14 +177,13 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   /** Test / internal: admit a message when open. */
   admit(msg: QqInboundMessage): void {
     if (!this.#open) return;
-    const target = formatInboundTarget(msg);
+    const conversation = qqInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: msg.id },
       content: formatInboundContent(msg),
       ...(msg.segments?.length ? { segments: msg.segments } : {}),
       sender: senderDisplayName(msg),
-      id: msg.id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
@@ -198,7 +196,7 @@ export class QqWebsocketEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'qq_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -249,8 +247,6 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   }
 }
 
-type ParsedSendTarget = ReturnType<typeof parseSendTarget>;
-
 export interface QqHttpEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
@@ -331,29 +327,27 @@ export class QqHttpEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const body = formatOutbound(payload);
-    const parsed = parseSendTarget(target);
+    const kind = qqOutboundKind(conversation);
     const bot = this.#requireBot();
     let result: unknown;
-    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 as ParsedSendTarget).kind)}`);
     }
-    return `${parsed.kind}-${parsed.id}:${resolveOutboundMessageId(result)}`;
+    return `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
   }
 
   async recallMessage(messageId: string): Promise<void> {
@@ -383,14 +377,13 @@ export class QqHttpEndpoint implements EndpointInstance {
 
   admit(msg: QqInboundMessage): void {
     if (!this.#open) return;
-    const target = formatInboundTarget(msg);
+    const conversation = qqInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: msg.id },
       content: formatInboundContent(msg),
       ...(msg.segments?.length ? { segments: msg.segments } : {}),
       sender: senderDisplayName(msg),
-      id: msg.id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
@@ -403,7 +396,7 @@ export class QqHttpEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'qq_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/index.ts

@@ -1,12 +1,9 @@
 export {
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundText,
-  parseSendTarget,
   resolveOutboundMessageId,
   resolveQqConfig,
   senderDisplayName,
-  type ParsedSendTarget,
   type QqAdapterConfig,
   type QqChannelKind,
   type QqInboundMessage,

package/src/protocol.ts

@@ -4,6 +4,7 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('qq');
@@ -92,11 +93,6 @@ export interface QqWireSegment {
   readonly data?: Record<string, unknown>;
 }
 
-export interface ParsedSendTarget {
-  readonly kind: QqChannelKind;
-  readonly id: string;
-}
-
 export function resolveQqConfig(config: QqAdapterConfig = {}): ResolvedQqConfig {
   const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
   const appid = pickCredential(config.appid, entry?.appid, process.env.QQ_APPID, process.env.QQ_BOT_APPID);
@@ -140,23 +136,25 @@ export function resolveQqConfig(config: QqAdapterConfig = {}): ResolvedQqConfig
 }
 
 /**
- * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ * 入站归一化 → ConversationRef：`direct`（频道私信）映射为 guild 容器内的
+ * private 会话；频道消息的所属 guild 进 `parent`。
  */
-export function formatInboundTarget(msg: QqInboundMessage): string {
-  return `${msg.channelKind}:${msg.channelId}`;
+export function qqInboundConversation(endpointId: string, msg: QqInboundMessage): ConversationRef {
+  const kind: ConversationKind = msg.channelKind === 'direct' ? 'private' : msg.channelKind;
+  return {
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind,
+    id: msg.channelId,
+    ...(msg.guildId && (msg.channelKind === 'channel' || msg.channelKind === 'direct')
+      ? { parent: { kind: 'channel' as const, id: msg.guildId } }
+      : {}),
+  };
 }
 
-export function parseSendTarget(target: string): ParsedSendTarget {
-  const sep = target.indexOf(':');
-  if (sep <= 0) {
-    return { kind: 'private', id: target };
-  }
-  const head = target.slice(0, sep);
-  const rest = target.slice(sep + 1);
-  if (head === 'private' || head === 'group' || head === 'channel' || head === 'direct') {
-    return { kind: head, id: rest };
-  }
-  return { kind: 'private', id: target };
+/** 出站：guild 容器内的 private 会话即 QQ `direct`（频道私信）。 */
+export function qqOutboundKind(conversation: ConversationRef): QqChannelKind {
+  if (conversation.kind === 'private' && conversation.parent?.kind === 'channel') return 'direct';
+  return conversation.kind;
 }
 
 export function senderDisplayName(msg: QqInboundMessage): string {