@zhin.js/adapter-napcat 6.0.1 → 6.0.3

package/CHANGELOG.md

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

package/README.md

@@ -24,8 +24,8 @@ pnpm add @zhin.js/adapter-napcat
 - `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-入站：`gateway.receive({ adapter, target: "private:uid"|"group:gid", content, sender, metadata })`  
-出站：`send({ target, payload })` → WS `send_private_msg` / `send_group_msg`
+入站：`gateway.receive({ conversation, message: { conversation, id }, content, sender, metadata })`（`conversation` 为 ConversationRef：私聊 `kind: 'private'`、群聊 `kind: 'group'`，临时会话群容器进 `parent`）  
+出站：`send({ conversation, payload })` → WS `send_private_msg` / `send_group_msg`
 
 ## 最小配置
 

package/lib/http-endpoint.d.ts

@@ -1,4 +1,4 @@
-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';
@@ -18,10 +18,7 @@ export declare class NapCatHttpEndpoint 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>;
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     admit(ev: NapCatEvent): void;

package/lib/http-endpoint.js

@@ -2,7 +2,7 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
-import { buildSendAction, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { buildSendAction, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
 import { readRequestBody } from './webhook.js';
 import { verifyNapCatAccessToken } from './wss-auth.js';
 const logger = getLogger('napcat');
@@ -48,9 +48,9 @@ export class NapCatHttpEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
-        const { action, params } = buildSendAction(target, message);
+        const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
         const resp = await this.#callHttpAction({
             http_url: this.#options.config.http_url,
             access_token: this.#options.config.access_token,
@@ -60,7 +60,7 @@ export class NapCatHttpEndpoint {
         logger.debug(formatCompact({
             op: 'napcat_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -87,15 +87,14 @@ export class NapCatHttpEndpoint {
         if (Array.isArray(ev.message) || typeof ev.message === 'string') {
             ev = { ...ev, message: normalizeMessage(ev.message) };
         }
-        const target = formatInboundTarget(ev);
+        const conversation = napcatInboundConversation(String(this.#options.id), ev);
         const nickname = senderNickname(ev);
         const mentioned = isNapCatBotMentioned(ev);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: msgId },
             content: formatInboundContent(ev),
             sender: senderUserId(ev),
-            id: msgId,
             metadata: Object.freeze({
                 message_type: ev.message_type,
                 user_id: ev.user_id != null ? String(ev.user_id) : undefined,
@@ -110,7 +109,7 @@ export class NapCatHttpEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'napcat_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 { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, parseSendTarget, resolveNapCatConfig, senderNickname, senderUserId, type MessageSegment, type NapCatActionRequest, type NapCatActionResponse, type NapCatAdapterConfig, type NapCatConfigBase, type NapCatEndpointConfig, type NapCatEvent, type NapCatHttpConfig, type NapCatMessageEvent, type NapCatSender, type NapCatWireSegment, type NapCatWsConfig, type NapCatWssConfig, type ParsedSendTarget, type ResolvedNapCatConfig, } from './protocol.js';
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, napcatInboundConversation, napcatOutboundTarget, resolveNapCatConfig, senderNickname, senderUserId, type MessageSegment, type NapCatActionRequest, type NapCatActionResponse, type NapCatAdapterConfig, type NapCatConfigBase, type NapCatEndpointConfig, type NapCatEvent, type NapCatHttpConfig, type NapCatMessageEvent, type NapCatSender, type NapCatWireSegment, type NapCatWsConfig, type NapCatWssConfig, type ParsedSendTarget, type ResolvedNapCatConfig, } from './protocol.js';
 export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 export { getEndpoint, getNapcatAgentDeps, registerNapcatAgentEndpoint, setNapcatAgentDeps, type NapcatAgentDeps, type NapcatAgentEndpoint, } from './napcat-agent-deps.js';
 export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, parseSendTarget, resolveNapCatConfig, senderNickname, senderUserId, } from './protocol.js';
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, napcatInboundConversation, napcatOutboundTarget, resolveNapCatConfig, senderNickname, senderUserId, } from './protocol.js';
 export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 export { getEndpoint, getNapcatAgentDeps, registerNapcatAgentEndpoint, setNapcatAgentDeps, } from './napcat-agent-deps.js';
 export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';

package/lib/protocol.d.ts

@@ -4,6 +4,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { type MediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Transitional legacy endpoint row (`endpoints[]` with `context: napcat`). */
 export interface NapCatLegacyEndpointRow {
     readonly context?: string;
@@ -116,8 +117,13 @@ export interface ParsedSendTarget {
 export declare function resolveNapCatConfig(config?: NapCatAdapterConfig): ResolvedNapCatConfig;
 export declare function isMessageEvent(ev: NapCatEvent): ev is NapCatMessageEvent;
 export declare function getChannelId(ev: NapCatEvent): string;
-export declare function formatInboundTarget(ev: NapCatEvent): string;
-export declare function parseSendTarget(target: string): ParsedSendTarget;
+/**
+ * 入站归一化 → ConversationRef：群消息 → kind 'group'；私聊临时会话
+ * （sub_type 'group'）→ kind 'private' + 群容器进 `parent`；其余私聊 → 'private'。
+ */
+export declare function napcatInboundConversation(endpointId: string, ev: NapCatEvent): ConversationRef;
+/** 出站：ConversationRef → OneBot 私聊/群聊目标。 */
+export declare function napcatOutboundTarget(conversation: ConversationRef): ParsedSendTarget;
 export declare function formatInboundContent(ev: NapCatEvent): string;
 /**
  * 入站 sender 语义：必须是用户 ID（Runtime Message contract）。
@@ -138,7 +144,7 @@ export declare function mediaRefToOneBotFile(media: MediaRef): string;
  * 非媒体的 wire 段（at 等）原样透传。
  */
 export declare function formatOutboundSegments(payload: unknown): MessageSegment[];
-export declare function buildSendAction(target: string, message: MessageSegment[]): {
+export declare function buildSendAction(target: ParsedSendTarget, message: MessageSegment[]): {
     action: string;
     params: Record<string, unknown>;
 };

package/lib/protocol.js

@@ -78,24 +78,32 @@ export function getChannelId(ev) {
         return String(ev.user_id);
     return '';
 }
-export function formatInboundTarget(ev) {
-    const messageType = ev.message_type === 'group' || (ev.group_id != null && ev.message_type !== 'private')
-        ? 'group'
-        : 'private';
-    return `${messageType}:${getChannelId(ev)}`;
-}
-export function parseSendTarget(target) {
-    const sep = target.indexOf(':');
-    if (sep <= 0) {
-        return { message_type: 'private', id: target };
+/**
+ * 入站归一化 → ConversationRef：群消息 → kind 'group'；私聊临时会话
+ * （sub_type 'group'）→ kind 'private' + 群容器进 `parent`；其余私聊 → 'private'。
+ */
+export function napcatInboundConversation(endpointId, ev) {
+    const endpoint = { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId };
+    const isGroup = ev.message_type === 'group' || (ev.group_id != null && ev.message_type !== 'private');
+    if (isGroup && ev.group_id != null) {
+        return { endpoint, kind: 'group', id: String(ev.group_id) };
     }
-    const head = target.slice(0, sep);
-    const rest = target.slice(sep + 1);
-    if (head === 'group')
-        return { message_type: 'group', id: rest };
-    if (head === 'private')
-        return { message_type: 'private', id: rest };
-    return { message_type: 'private', id: target };
+    if (ev.sub_type === 'group' && ev.group_id != null) {
+        return {
+            endpoint,
+            kind: 'private',
+            id: ev.user_id != null ? String(ev.user_id) : '',
+            parent: { kind: 'group', id: String(ev.group_id) },
+        };
+    }
+    return { endpoint, kind: 'private', id: ev.user_id != null ? String(ev.user_id) : '' };
+}
+/** 出站：ConversationRef → OneBot 私聊/群聊目标。 */
+export function napcatOutboundTarget(conversation) {
+    return {
+        message_type: conversation.kind === 'group' ? 'group' : 'private',
+        id: conversation.id,
+    };
 }
 export function formatInboundContent(ev) {
     if (typeof ev.raw_message === 'string' && ev.raw_message)
@@ -231,12 +239,11 @@ export function formatOutboundSegments(payload) {
     return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }
 export function buildSendAction(target, message) {
-    const parsed = parseSendTarget(target);
-    if (parsed.message_type === 'group') {
+    if (target.message_type === 'group') {
         return {
             action: 'send_group_msg',
             params: {
-                group_id: Number(parsed.id) || parsed.id,
+                group_id: Number(target.id) || target.id,
                 message,
             },
         };
@@ -244,7 +251,7 @@ export function buildSendAction(target, message) {
     return {
         action: 'send_private_msg',
         params: {
-            user_id: Number(parsed.id) || parsed.id,
+            user_id: Number(target.id) || target.id,
             message,
         },
     };

package/lib/ws-endpoint.d.ts

@@ -1,4 +1,4 @@
-import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type NapCatEvent, type NapCatWsConfig } from './protocol.js';
@@ -17,10 +17,7 @@ export declare class NapCatWsEndpoint 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>;
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;

package/lib/ws-endpoint.js

@@ -7,7 +7,7 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
-import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
 import { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, } from './ws-transport.js';
 const logger = getLogger('napcat');
 export class NapCatWsEndpoint {
@@ -70,15 +70,15 @@ export class NapCatWsEndpoint {
             this.#ws = undefined;
         }
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
-        const { action, params } = buildSendAction(target, message);
+        const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
         const data = await this.callApi(action, params);
         const messageId = data?.message_id != null ? String(data.message_id) : '';
         logger.debug(formatCompact({
             op: 'napcat_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -237,16 +237,15 @@ export class NapCatWsEndpoint {
         if (Array.isArray(ev.message) || typeof ev.message === 'string') {
             ev = { ...ev, message: normalizeMessage(ev.message) };
         }
-        const target = formatInboundTarget(ev);
+        const conversation = napcatInboundConversation(String(this.#options.id), ev);
         const content = formatInboundContent(ev);
         const nickname = senderNickname(ev);
         const mentioned = isNapCatBotMentioned(ev);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: msgId },
             content,
             sender: senderUserId(ev),
-            id: msgId,
             metadata: Object.freeze({
                 message_type: ev.message_type,
                 user_id: ev.user_id != null ? String(ev.user_id) : undefined,
@@ -261,7 +260,7 @@ export class NapCatWsEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'napcat_gateway_receive_failed',
-                target,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/wss-endpoint.d.ts

@@ -1,4 +1,4 @@
-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';
@@ -17,10 +17,7 @@ export declare class NapCatWssEndpoint 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>;
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     admit(ev: NapCatEvent): void;

package/lib/wss-endpoint.js

@@ -6,7 +6,7 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
-import { buildSendAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { buildSendAction, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
 import { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, startNapCatHeartbeat, } from './ws-transport.js';
 import { verifyNapCatAccessToken } from './wss-auth.js';
 const logger = getLogger('napcat');
@@ -70,9 +70,9 @@ export class NapCatWssEndpoint {
         }
         this.#started = false;
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
-        const { action, params } = buildSendAction(target, message);
+        const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
         const data = await this.callApi(action, params);
         return data?.message_id != null ? String(data.message_id) : '';
     }
@@ -95,15 +95,14 @@ export class NapCatWssEndpoint {
         if (Array.isArray(ev.message) || typeof ev.message === 'string') {
             ev = { ...ev, message: normalizeMessage(ev.message) };
         }
-        const target = formatInboundTarget(ev);
+        const conversation = napcatInboundConversation(String(this.#options.id), ev);
         const nickname = senderNickname(ev);
         const mentioned = isNapCatBotMentioned(ev);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: msgId },
             content: formatInboundContent(ev),
             sender: senderUserId(ev),
-            id: msgId,
             metadata: Object.freeze({
                 message_type: ev.message_type,
                 user_id: ev.user_id != null ? String(ev.user_id) : undefined,
@@ -118,7 +117,7 @@ export class NapCatWssEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'napcat_gateway_receive_failed',
-                target,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "6.0.1",
+  "version": "6.0.3",
   "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
@@ -43,12 +43,13 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@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"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -56,16 +57,16 @@
     "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/agent": "1.1.3",
+    "@zhin.js/host-http": "1.0.6"
   },
   "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": {

package/src/http-endpoint.ts

@@ -2,7 +2,7 @@
  * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-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, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -19,9 +19,10 @@ import {
   buildSendAction,
   callNapCatHttpAction,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   isMessageEvent,
+  napcatInboundConversation,
+  napcatOutboundTarget,
   senderNickname,
   senderUserId,
   type NapCatEvent,
@@ -90,9 +91,9 @@ export class NapCatHttpEndpoint 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 message = formatOutboundSegments(payload);
-    const { action, params } = buildSendAction(target, message);
+    const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
     const resp = await this.#callHttpAction(
       {
         http_url: this.#options.config.http_url,
@@ -106,7 +107,7 @@ export class NapCatHttpEndpoint implements EndpointInstance {
     logger.debug(formatCompact({
       op: 'napcat_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -136,15 +137,14 @@ export class NapCatHttpEndpoint implements EndpointInstance {
     if (Array.isArray(ev.message) || typeof ev.message === 'string') {
       ev = { ...ev, message: normalizeMessage(ev.message) };
     }
-    const target = formatInboundTarget(ev);
+    const conversation = napcatInboundConversation(String(this.#options.id), ev);
     const nickname = senderNickname(ev);
     const mentioned = isNapCatBotMentioned(ev);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: msgId },
       content: formatInboundContent(ev),
       sender: senderUserId(ev),
-      id: msgId,
       metadata: Object.freeze({
         message_type: ev.message_type,
         user_id: ev.user_id != null ? String(ev.user_id) : undefined,
@@ -159,7 +159,7 @@ export class NapCatHttpEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'napcat_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/index.ts

@@ -3,12 +3,12 @@ export {
   buildWsConnectOptions,
   callNapCatHttpAction,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   getChannelId,
   isMessageEvent,
   mediaRefToOneBotFile,
-  parseSendTarget,
+  napcatInboundConversation,
+  napcatOutboundTarget,
   resolveNapCatConfig,
   senderNickname,
   senderUserId,

package/src/protocol.ts

@@ -4,6 +4,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { isMediaRef, type MediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('napcat');
@@ -213,23 +214,33 @@ export function getChannelId(ev: NapCatEvent): string {
   return '';
 }
 
-export function formatInboundTarget(ev: NapCatEvent): string {
-  const messageType = ev.message_type === 'group' || (ev.group_id != null && ev.message_type !== 'private')
-    ? 'group'
-    : 'private';
-  return `${messageType}:${getChannelId(ev)}`;
+/**
+ * 入站归一化 → ConversationRef：群消息 → kind 'group'；私聊临时会话
+ * （sub_type 'group'）→ kind 'private' + 群容器进 `parent`；其余私聊 → 'private'。
+ */
+export function napcatInboundConversation(endpointId: string, ev: NapCatEvent): ConversationRef {
+  const endpoint = { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId };
+  const isGroup = ev.message_type === 'group' || (ev.group_id != null && ev.message_type !== 'private');
+  if (isGroup && ev.group_id != null) {
+    return { endpoint, kind: 'group', id: String(ev.group_id) };
+  }
+  if (ev.sub_type === 'group' && ev.group_id != null) {
+    return {
+      endpoint,
+      kind: 'private',
+      id: ev.user_id != null ? String(ev.user_id) : '',
+      parent: { kind: 'group', id: String(ev.group_id) },
+    };
+  }
+  return { endpoint, kind: 'private', id: ev.user_id != null ? String(ev.user_id) : '' };
 }
 
-export function parseSendTarget(target: string): ParsedSendTarget {
-  const sep = target.indexOf(':');
-  if (sep <= 0) {
-    return { message_type: 'private', id: target };
-  }
-  const head = target.slice(0, sep);
-  const rest = target.slice(sep + 1);
-  if (head === 'group') return { message_type: 'group', id: rest };
-  if (head === 'private') return { message_type: 'private', id: rest };
-  return { message_type: 'private', id: target };
+/** 出站：ConversationRef → OneBot 私聊/群聊目标。 */
+export function napcatOutboundTarget(conversation: ConversationRef): ParsedSendTarget {
+  return {
+    message_type: conversation.kind === 'group' ? 'group' : 'private',
+    id: conversation.id,
+  };
 }
 
 export function formatInboundContent(ev: NapCatEvent): string {
@@ -373,15 +384,14 @@ export function formatOutboundSegments(payload: unknown): MessageSegment[] {
 }
 
 export function buildSendAction(
-  target: string,
+  target: ParsedSendTarget,
   message: MessageSegment[],
 ): { action: string; params: Record<string, unknown> } {
-  const parsed = parseSendTarget(target);
-  if (parsed.message_type === 'group') {
+  if (target.message_type === 'group') {
     return {
       action: 'send_group_msg',
       params: {
-        group_id: Number(parsed.id) || parsed.id,
+        group_id: Number(target.id) || target.id,
         message,
       },
     };
@@ -389,7 +399,7 @@ export function buildSendAction(
   return {
     action: 'send_private_msg',
     params: {
-      user_id: Number(parsed.id) || parsed.id,
+      user_id: Number(target.id) || target.id,
       message,
     },
   };

package/src/ws-endpoint.ts

@@ -8,6 +8,7 @@ import {
   type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
+  type EndpointSendRequest,
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -24,9 +25,10 @@ import {
   buildSendAction,
   buildWsConnectOptions,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   isMessageEvent,
+  napcatInboundConversation,
+  napcatOutboundTarget,
   senderNickname,
   senderUserId,
   type NapCatEvent,
@@ -118,15 +120,15 @@ export class NapCatWsEndpoint implements EndpointInstance {
     }
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
-    const { action, params } = buildSendAction(target, message);
+    const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
     const data = await this.callApi(action, params) as { message_id?: number | string } | undefined;
     const messageId = data?.message_id != null ? String(data.message_id) : '';
     logger.debug(formatCompact({
       op: 'napcat_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -326,16 +328,15 @@ export class NapCatWsEndpoint implements EndpointInstance {
     if (Array.isArray(ev.message) || typeof ev.message === 'string') {
       ev = { ...ev, message: normalizeMessage(ev.message) };
     }
-    const target = formatInboundTarget(ev);
+    const conversation = napcatInboundConversation(String(this.#options.id), ev);
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);
     const mentioned = isNapCatBotMentioned(ev);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: msgId },
       content,
       sender: senderUserId(ev),
-      id: msgId,
       metadata: Object.freeze({
         message_type: ev.message_type,
         user_id: ev.user_id != null ? String(ev.user_id) : undefined,
@@ -350,7 +351,7 @@ export class NapCatWsEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'napcat_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/wss-endpoint.ts

@@ -2,7 +2,7 @@
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
 import { clearInterval } from 'node:timers';
-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, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -18,9 +18,10 @@ import {
 import {
   buildSendAction,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   isMessageEvent,
+  napcatInboundConversation,
+  napcatOutboundTarget,
   senderNickname,
   senderUserId,
   type NapCatEvent,
@@ -115,9 +116,9 @@ export class NapCatWssEndpoint implements EndpointInstance {
     this.#started = false;
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
-    const { action, params } = buildSendAction(target, message);
+    const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
     const data = await this.callApi(action, params) as { message_id?: number | string } | undefined;
     return data?.message_id != null ? String(data.message_id) : '';
   }
@@ -139,15 +140,14 @@ export class NapCatWssEndpoint implements EndpointInstance {
     if (Array.isArray(ev.message) || typeof ev.message === 'string') {
       ev = { ...ev, message: normalizeMessage(ev.message) };
     }
-    const target = formatInboundTarget(ev);
+    const conversation = napcatInboundConversation(String(this.#options.id), ev);
     const nickname = senderNickname(ev);
     const mentioned = isNapCatBotMentioned(ev);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: msgId },
       content: formatInboundContent(ev),
       sender: senderUserId(ev),
-      id: msgId,
       metadata: Object.freeze({
         message_type: ev.message_type,
         user_id: ev.user_id != null ? String(ev.user_id) : undefined,
@@ -162,7 +162,7 @@ export class NapCatWssEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'napcat_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });