@zhin.js/adapter-icqq 8.0.1 → 8.0.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @zhin.js/adapter-icqq
 
+## 8.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/agent@1.1.3
+  - zhin.js@6.0.2
+
+## 8.0.2
+
+### Patch Changes
+
+- Updated dependencies [696ab1b]
+  - @zhin.js/agent@1.1.2
+  - zhin.js@6.0.1
+
 ## 8.0.1
 
 ### Patch Changes

package/README.md

@@ -5,8 +5,8 @@ ICQQ Plugin Runtime 适配器 — 通过 [@icqqjs/cli](https://github.com/icqqjs
 ## 功能特性
 
 - 群聊 / 私聊 / 群临时会话 / QQ 频道消息
-- 入站：`messageGatewayToken`（IPC 事件订阅）
-- 出站：`send({ target, payload })` → `send_group_msg` / `send_private_msg` / …
+- 入站：`messageGatewayToken`（IPC 事件订阅），归一为 `gateway.receive({ conversation, message, content, ... })`
+- 出站：`send({ conversation, payload })` → `send_group_msg` / `send_private_msg` / …（conversation kind/id/parent 路由）
 - Agent 工具：`agent/tools/`（戳一戳、群管、好友列表等）保留
 - Console Endpoint 管理：`src/endpoint.ts` 显式实现 `EndpointManagement`（好友/群/群成员列表、请求审批、删好友、踢人、禁言、设管理），Console 使用 `endpoint.friends` / `endpoint.groups` / `endpoint.group_members` 等规范 RPC
 
@@ -48,14 +48,14 @@ plugins:
 
 先执行 `icqq login`，再启动 Zhin。
 
-## Send target
+## Send conversation
 
-| 类型 | target |
-|------|--------|
-| 私聊 | `private:uin` |
-| 群聊 | `group:gid` |
-| 群临时会话 | `temp:gid:uin` |
-| 频道 | `channel:guildId:channelId` |
+| 类型 | conversation |
+|------|--------------|
+| 私聊 | `{ kind: 'private', id: uin }` |
+| 群聊 | `{ kind: 'group', id: gid }` |
+| 群临时会话 | `{ kind: 'private', id: uin, parent: { kind: 'group', id: gid } }` |
+| 频道 | `{ kind: 'channel', id: channelId, parent: { kind: 'channel', id: guildId } }` |
 
 ## 架构
 

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import type { EndpointControl, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointControl, EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type IcqqInboundMessage, type IpcEvent, type IpcResponse, type ResolvedIcqqConfig } from './protocol.js';
@@ -48,10 +48,7 @@ export declare class IcqqIpcEndpoint 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>;
     private static readonly EMOJI_MAP;
     private getEmojiId;
     /** Activity-feedback / OutboundHost reaction surface. */

package/lib/endpoint.js

@@ -5,7 +5,7 @@ import { buildIcqqInboxNoticeRow, buildIcqqInboxRequestRow, buildIcqqSystemReque
 import { IcqqGuildCatalog, isIcqqGuildIpcEvent, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 import { IpcClient } from './ipc-client.js';
 import { materializeOutboundBase64, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
-import { Actions, formatInboundContent, formatInboundTarget, formatOutboundBody, parseSendTarget, } from './protocol.js';
+import { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 const logger = getLogger('icqq');
 export class IcqqIpcEndpoint {
     #options;
@@ -187,7 +187,7 @@ export class IcqqIpcEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         if (!this.ipc) {
             throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发送消息`);
         }
@@ -196,7 +196,7 @@ export class IcqqIpcEndpoint {
             ? materializeOutboundBase64(payload, mediaMode)
             : payload;
         const message = formatOutboundBody(content);
-        const parsed = parseSendTarget(target);
+        const parsed = icqqOutboundTarget(conversation);
         let action;
         let params;
         switch (parsed.kind) {
@@ -233,7 +233,7 @@ export class IcqqIpcEndpoint {
         logger.debug(formatCompact({
             op: 'icqq_send',
             endpoint: this.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -499,13 +499,14 @@ export class IcqqIpcEndpoint {
     }
     /** Test / internal: admit when open. */
     admit(msg) {
+        const conversation = msg.conversation;
         if (!this.#open) {
             logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'endpoint_closed',
                 endpoint: this.name,
                 id: msg.id,
-                target: msg.target,
+                target: `${conversation.kind}:${conversation.id}`,
             }));
             return;
         }
@@ -519,7 +520,7 @@ export class IcqqIpcEndpoint {
             op: 'icqq_inbound_admit',
             endpoint: this.name,
             id: msg.id,
-            target: msg.target,
+            target: `${conversation.kind}:${conversation.id}`,
             sender: msg.sender,
             channelType: msg.channelType,
             mentioned: mentioned || undefined,
@@ -527,12 +528,11 @@ export class IcqqIpcEndpoint {
             segments: summarizeSegmentTypes(msg.segments),
         }));
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: msg.target,
+            conversation,
+            message: { conversation, id: msg.id },
             content: msg.content,
             ...(msg.segments ? { segments: msg.segments } : {}),
             sender: msg.sender,
-            id: msg.id,
             metadata: Object.freeze({
                 endpoint: this.name,
                 channelType: msg.channelType,
@@ -542,7 +542,7 @@ export class IcqqIpcEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'icqq_gateway_receive_failed',
-                target: msg.target,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -616,7 +616,7 @@ export class IcqqIpcEndpoint {
         }
         this.admit({
             id: normalized.messageId,
-            target: formatInboundTarget({
+            conversation: icqqInboundConversation(String(this.#options.id), {
                 channelType: normalized.channelType,
                 channelId: normalized.channelId,
                 channelParentGroupId: normalized.channelParentGroupId,
@@ -656,7 +656,7 @@ export class IcqqIpcEndpoint {
         }
         this.admit({
             id: normalized.messageId,
-            target: formatInboundTarget({
+            conversation: icqqInboundConversation(String(this.#options.id), {
                 channelType: 'channel',
                 channelId: normalized.channelId,
                 guildId: normalized.guildId,

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { Actions, formatInboundContent, formatInboundTarget, formatOutboundBody, parseSendTarget, resolveIcqqConfig, type IcqqAdapterConfig, type IcqqInboundMessage, type IcqqWireSegment, type IpcEvent, type IpcMessage, type IpcRequest, type IpcResponse, type ParsedIcqqSendTarget, type ResolvedIcqqConfig, } from './protocol.js';
+export { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, resolveIcqqConfig, type IcqqAdapterConfig, type IcqqInboundMessage, type IcqqWireSegment, type IpcEvent, type IpcMessage, type IpcRequest, type IpcResponse, type ParsedIcqqSendTarget, type ResolvedIcqqConfig, } from './protocol.js';
 export { IcqqIpcEndpoint, type CreateIcqqIpc, type IcqqEndpointOptions, type IcqqInboxHooks, type IcqqIpcTransport, } from './endpoint.js';
 export * from './types.js';
 export { getIcqqAgentDeps, registerIcqqAgentEndpoint, setIcqqAgentDeps, type IcqqAgentDeps, type IcqqAgentEndpoint, } from './icqq-agent-deps.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { Actions, formatInboundContent, formatInboundTarget, formatOutboundBody, parseSendTarget, resolveIcqqConfig, } from './protocol.js';
+export { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, resolveIcqqConfig, } from './protocol.js';
 export { IcqqIpcEndpoint, } from './endpoint.js';
 export * from './types.js';
 export { getIcqqAgentDeps, registerIcqqAgentEndpoint, setIcqqAgentDeps, } from './icqq-agent-deps.js';

package/lib/ipc-client.d.ts

@@ -61,7 +61,7 @@ export declare class IpcClient {
      */
     request(action: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<IpcResponse>;
     /**
-     * @deprecated 兼容旧调用方式：服务端已自动推送事件，type/id 过滤在客户端完成。
+     * 订阅 daemon 推送事件：服务端自动推送全部事件，type/id 过滤在客户端完成。
      * @returns 订阅句柄，包含 unsubscribe() 方法
      */
     subscribe(_action: string, params: Record<string, unknown>, onEvent: (event: IpcEvent) => void): {

package/lib/ipc-client.js

@@ -310,7 +310,7 @@ export class IpcClient {
         });
     }
     /**
-     * @deprecated 兼容旧调用方式：服务端已自动推送事件，type/id 过滤在客户端完成。
+     * 订阅 daemon 推送事件：服务端自动推送全部事件，type/id 过滤在客户端完成。
      * @returns 订阅句柄，包含 unsubscribe() 方法
      */
     subscribe(_action, params, onEvent) {

package/lib/protocol.d.ts

@@ -11,6 +11,7 @@
  *
  * 登录相关：**推送**走 IpcEvent（`system.login.*`）。
  */
+import type { ConversationRef } from '@zhin.js/im-contract';
 import type { MessageSegment } from "zhin.js";
 /** CLI → Daemon 请求 */
 export type IpcRequest = {
@@ -236,7 +237,7 @@ export interface IcqqWireSegment {
 }
 export interface IcqqInboundMessage {
     readonly id: string;
-    readonly target: string;
+    readonly conversation: ConversationRef;
     readonly content: string;
     /**
      * 结构化段视图（canonical Segment，经 toCanonicalSegments 归一）。
@@ -263,13 +264,20 @@ export type ParsedIcqqSendTarget = {
     readonly channelId: string;
 };
 export declare function resolveIcqqConfig(config?: IcqqAdapterConfig): ResolvedIcqqConfig;
-/** Gateway reply target: `private:uid` / `group:gid` / `temp:gid:uid` / `channel:guild:channel`. */
-export declare function formatInboundTarget(input: {
+/**
+ * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
+ * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
+ */
+export declare function icqqInboundConversation(endpointId: string, input: {
     readonly channelType: 'private' | 'group' | 'channel';
     readonly channelId: string;
     readonly channelParentGroupId?: string;
     readonly guildId?: string;
-}): string;
-export declare function parseSendTarget(target: string): ParsedIcqqSendTarget;
+}): ConversationRef;
+/**
+ * 出站：从 ConversationRef 派生 IPC action 路由。
+ * 群容器（parent kind 'group'）内的 private 会话即 ICQQ 群临时会话（temp）。
+ */
+export declare function icqqOutboundTarget(conversation: ConversationRef): ParsedIcqqSendTarget;
 export declare function formatOutboundBody(payload: unknown): string;
 export declare function formatInboundContent(rawMessage: string): string;

package/lib/protocol.js

@@ -206,47 +206,53 @@ export function resolveIcqqConfig(config = {}) {
         ...(rpc ? { rpc } : {}),
     };
 }
-/** Gateway reply target: `private:uid` / `group:gid` / `temp:gid:uid` / `channel:guild:channel`. */
-export function formatInboundTarget(input) {
+/**
+ * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
+ * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
+ */
+export function icqqInboundConversation(endpointId, input) {
+    const endpoint = { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId };
     if (input.channelType === 'private' && input.channelParentGroupId) {
-        return `temp:${input.channelParentGroupId}:${input.channelId}`;
+        return {
+            endpoint,
+            kind: 'private',
+            id: input.channelId,
+            parent: { kind: 'group', id: input.channelParentGroupId },
+        };
     }
     if (input.channelType === 'channel' && input.guildId) {
-        return `channel:${input.guildId}:${input.channelId}`;
+        return {
+            endpoint,
+            kind: 'channel',
+            id: input.channelId,
+            parent: { kind: 'channel', id: input.guildId },
+        };
     }
-    return `${input.channelType}:${input.channelId}`;
+    return { endpoint, kind: input.channelType, id: input.channelId };
 }
-export function parseSendTarget(target) {
-    const trimmed = target.trim();
-    if (trimmed.startsWith('temp:')) {
-        const rest = trimmed.slice(5);
-        const [groupId, userId] = rest.split(':');
-        if (!groupId || !userId)
-            throw new TypeError(`Invalid icqq temp target: ${target}`);
-        return { kind: 'temp', groupId: Number(groupId), userId: Number(userId) };
-    }
-    if (trimmed.startsWith('channel:')) {
-        const rest = trimmed.slice(8);
-        const idx = rest.indexOf(':');
-        if (idx <= 0)
-            throw new TypeError(`Invalid icqq channel target: ${target}`);
+/**
+ * 出站：从 ConversationRef 派生 IPC action 路由。
+ * 群容器（parent kind 'group'）内的 private 会话即 ICQQ 群临时会话（temp）。
+ */
+export function icqqOutboundTarget(conversation) {
+    if (conversation.kind === 'private' && conversation.parent?.kind === 'group') {
         return {
-            kind: 'channel',
-            guildId: rest.slice(0, idx),
-            channelId: rest.slice(idx + 1),
+            kind: 'temp',
+            groupId: Number(conversation.parent.id),
+            userId: Number(conversation.id),
         };
     }
-    if (trimmed.startsWith('private:')) {
-        return { kind: 'private', userId: Number(trimmed.slice(8)) };
+    if (conversation.kind === 'private') {
+        return { kind: 'private', userId: Number(conversation.id) };
     }
-    if (trimmed.startsWith('group:')) {
-        return { kind: 'group', groupId: Number(trimmed.slice(6)) };
+    if (conversation.kind === 'group') {
+        return { kind: 'group', groupId: Number(conversation.id) };
     }
-    // Bare numeric id → private (common reply path)
-    if (/^\d+$/.test(trimmed)) {
-        return { kind: 'private', userId: Number(trimmed) };
+    const guildId = conversation.parent?.kind === 'channel' ? conversation.parent.id : undefined;
+    if (!guildId) {
+        throw new TypeError(`Invalid icqq channel conversation (missing guild parent): ${conversation.id}`);
     }
-    throw new TypeError(`Invalid icqq send target: ${target}`);
+    return { kind: 'channel', guildId, channelId: conversation.id };
 }
 export function formatOutboundBody(payload) {
     if (typeof payload === 'string') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "8.0.1",
+  "version": "8.0.3",
   "description": "Zhin.js ICQQ adapter for Plugin Runtime (IPC daemon client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,19 +34,20 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@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": {
@@ -64,8 +65,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.1",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -1,7 +1,12 @@
 /**
  * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import type { EndpointControl, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type {
+  EndpointControl,
+  EndpointInstance,
+  EndpointManagement,
+  EndpointSendRequest,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -38,9 +43,9 @@ import {
 import {
   Actions,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundBody,
-  parseSendTarget,
+  icqqInboundConversation,
+  icqqOutboundTarget,
   type IcqqInboundMessage,
   type IpcEvent,
   type IpcResponse,
@@ -265,7 +270,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     if (!this.ipc) {
       throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发送消息`);
     }
@@ -274,7 +279,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       ? materializeOutboundBase64(payload, mediaMode)
       : payload;
     const message = formatOutboundBody(content);
-    const parsed = parseSendTarget(target);
+    const parsed = icqqOutboundTarget(conversation);
     let action: string;
     let params: Record<string, unknown>;
     switch (parsed.kind) {
@@ -313,7 +318,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     logger.debug(formatCompact({
       op: 'icqq_send',
       endpoint: this.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -630,13 +635,14 @@ export class IcqqIpcEndpoint implements EndpointInstance {
 
   /** Test / internal: admit when open. */
   admit(msg: IcqqInboundMessage): void {
+    const conversation = msg.conversation;
     if (!this.#open) {
       logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'endpoint_closed',
         endpoint: this.name,
         id: msg.id,
-        target: msg.target,
+        target: `${conversation.kind}:${conversation.id}`,
       }));
       return;
     }
@@ -650,7 +656,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       op: 'icqq_inbound_admit',
       endpoint: this.name,
       id: msg.id,
-      target: msg.target,
+      target: `${conversation.kind}:${conversation.id}`,
       sender: msg.sender,
       channelType: msg.channelType,
       mentioned: mentioned || undefined,
@@ -658,12 +664,11 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       segments: summarizeSegmentTypes(msg.segments),
     }));
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: msg.target,
+      conversation,
+      message: { conversation, id: msg.id },
       content: msg.content,
       ...(msg.segments ? { segments: msg.segments } : {}),
       sender: msg.sender,
-      id: msg.id,
       metadata: Object.freeze({
         endpoint: this.name,
         channelType: msg.channelType,
@@ -673,7 +678,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'icqq_gateway_receive_failed',
-        target: msg.target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -747,7 +752,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }
     this.admit({
       id: normalized.messageId,
-      target: formatInboundTarget({
+      conversation: icqqInboundConversation(String(this.#options.id), {
         channelType: normalized.channelType,
         channelId: normalized.channelId,
         channelParentGroupId: normalized.channelParentGroupId,
@@ -789,7 +794,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }
     this.admit({
       id: normalized.messageId,
-      target: formatInboundTarget({
+      conversation: icqqInboundConversation(String(this.#options.id), {
         channelType: 'channel',
         channelId: normalized.channelId,
         guildId: normalized.guildId,

package/src/index.ts

@@ -1,9 +1,9 @@
 export {
   Actions,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundBody,
-  parseSendTarget,
+  icqqInboundConversation,
+  icqqOutboundTarget,
   resolveIcqqConfig,
   type IcqqAdapterConfig,
   type IcqqInboundMessage,

package/src/ipc-client.ts

@@ -366,7 +366,7 @@ export class IpcClient {
   }
 
   /**
-   * @deprecated 兼容旧调用方式：服务端已自动推送事件，type/id 过滤在客户端完成。
+   * 订阅 daemon 推送事件：服务端自动推送全部事件，type/id 过滤在客户端完成。
    * @returns 订阅句柄，包含 unsubscribe() 方法
    */
   subscribe(

package/src/protocol.ts

@@ -13,6 +13,7 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import type { MessageSegment } from "zhin.js";
 import { resolveCqMediaArg } from "./cq-message.js";
 
@@ -313,7 +314,7 @@ export interface IcqqWireSegment {
 
 export interface IcqqInboundMessage {
   readonly id: string;
-  readonly target: string;
+  readonly conversation: ConversationRef;
   readonly content: string;
   /**
    * 结构化段视图（canonical Segment，经 toCanonicalSegments 归一）。
@@ -354,51 +355,59 @@ export function resolveIcqqConfig(config: IcqqAdapterConfig = {}): ResolvedIcqqC
   };
 }
 
-/** Gateway reply target: `private:uid` / `group:gid` / `temp:gid:uid` / `channel:guild:channel`. */
-export function formatInboundTarget(input: {
+/**
+ * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
+ * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
+ */
+export function icqqInboundConversation(endpointId: string, input: {
   readonly channelType: 'private' | 'group' | 'channel';
   readonly channelId: string;
   readonly channelParentGroupId?: string;
   readonly guildId?: string;
-}): string {
+}): ConversationRef {
+  const endpoint = { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId };
   if (input.channelType === 'private' && input.channelParentGroupId) {
-    return `temp:${input.channelParentGroupId}:${input.channelId}`;
+    return {
+      endpoint,
+      kind: 'private',
+      id: input.channelId,
+      parent: { kind: 'group', id: input.channelParentGroupId },
+    };
   }
   if (input.channelType === 'channel' && input.guildId) {
-    return `channel:${input.guildId}:${input.channelId}`;
+    return {
+      endpoint,
+      kind: 'channel',
+      id: input.channelId,
+      parent: { kind: 'channel', id: input.guildId },
+    };
   }
-  return `${input.channelType}:${input.channelId}`;
+  return { endpoint, kind: input.channelType, id: input.channelId };
 }
 
-export function parseSendTarget(target: string): ParsedIcqqSendTarget {
-  const trimmed = target.trim();
-  if (trimmed.startsWith('temp:')) {
-    const rest = trimmed.slice(5);
-    const [groupId, userId] = rest.split(':');
-    if (!groupId || !userId) throw new TypeError(`Invalid icqq temp target: ${target}`);
-    return { kind: 'temp', groupId: Number(groupId), userId: Number(userId) };
-  }
-  if (trimmed.startsWith('channel:')) {
-    const rest = trimmed.slice(8);
-    const idx = rest.indexOf(':');
-    if (idx <= 0) throw new TypeError(`Invalid icqq channel target: ${target}`);
+/**
+ * 出站：从 ConversationRef 派生 IPC action 路由。
+ * 群容器（parent kind 'group'）内的 private 会话即 ICQQ 群临时会话（temp）。
+ */
+export function icqqOutboundTarget(conversation: ConversationRef): ParsedIcqqSendTarget {
+  if (conversation.kind === 'private' && conversation.parent?.kind === 'group') {
     return {
-      kind: 'channel',
-      guildId: rest.slice(0, idx),
-      channelId: rest.slice(idx + 1),
+      kind: 'temp',
+      groupId: Number(conversation.parent.id),
+      userId: Number(conversation.id),
     };
   }
-  if (trimmed.startsWith('private:')) {
-    return { kind: 'private', userId: Number(trimmed.slice(8)) };
+  if (conversation.kind === 'private') {
+    return { kind: 'private', userId: Number(conversation.id) };
   }
-  if (trimmed.startsWith('group:')) {
-    return { kind: 'group', groupId: Number(trimmed.slice(6)) };
+  if (conversation.kind === 'group') {
+    return { kind: 'group', groupId: Number(conversation.id) };
   }
-  // Bare numeric id → private (common reply path)
-  if (/^\d+$/.test(trimmed)) {
-    return { kind: 'private', userId: Number(trimmed) };
+  const guildId = conversation.parent?.kind === 'channel' ? conversation.parent.id : undefined;
+  if (!guildId) {
+    throw new TypeError(`Invalid icqq channel conversation (missing guild parent): ${conversation.id}`);
   }
-  throw new TypeError(`Invalid icqq send target: ${target}`);
+  return { kind: 'channel', guildId, channelId: conversation.id };
 }
 
 export function formatOutboundBody(payload: unknown): string {