@zhin.js/adapter-napcat 6.0.2 → 6.0.5

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');
@@ -12,7 +13,7 @@ const logger = getLogger('napcat');
 export interface NapCatLegacyEndpointRow {
   readonly context?: string;
   readonly connection?: 'ws' | 'wss' | 'http';
-  readonly name?: string;
+  readonly id?: string;
   readonly access_token?: string;
   readonly url?: string;
   readonly path?: string;
@@ -26,7 +27,7 @@ export interface NapCatLegacyEndpointRow {
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface NapCatAdapterConfig {
   readonly connection?: 'ws' | 'wss' | 'http';
-  readonly name?: string;
+  readonly id?: string;
   readonly access_token?: string;
   readonly url?: string;
   readonly path?: string;
@@ -41,7 +42,7 @@ export interface NapCatAdapterConfig {
 
 export interface NapCatConfigBase {
   readonly context: 'napcat';
-  readonly name: string;
+  readonly id: string;
   readonly access_token?: string;
 }
 
@@ -142,8 +143,8 @@ function normalizeConnection(
 export function resolveNapCatConfig(config: NapCatAdapterConfig = {}): ResolvedNapCatConfig {
   const entry = config.endpoints?.find((item) => item.context === 'napcat');
   const connection = normalizeConnection(config.connection ?? entry?.connection);
-  const name = (typeof config.name === 'string' && config.name)
-    || (typeof entry?.name === 'string' && entry.name)
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
     || process.env.NAPCAT_BOT_NAME
     || 'napcat-bot';
   const access_token = config.access_token ?? entry?.access_token;
@@ -158,7 +159,7 @@ export function resolveNapCatConfig(config: NapCatAdapterConfig = {}): ResolvedN
     return {
       context: 'napcat',
       connection: 'ws',
-      name,
+      id,
       access_token,
       url,
       reconnect_interval: config.reconnect_interval ?? entry?.reconnect_interval ?? 5000,
@@ -172,7 +173,7 @@ export function resolveNapCatConfig(config: NapCatAdapterConfig = {}): ResolvedN
     return {
       context: 'napcat',
       connection: 'wss',
-      name,
+      id,
       access_token,
       path,
       heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
@@ -188,7 +189,7 @@ export function resolveNapCatConfig(config: NapCatAdapterConfig = {}): ResolvedN
     return {
       context: 'napcat',
       connection: 'http',
-      name,
+      id,
       access_token,
       http_url,
       post_path,
@@ -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(endpointKey: string, ev: NapCatEvent): ConversationRef {
+  const endpoint = { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey };
+  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,9 +8,10 @@ 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';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
@@ -24,9 +25,10 @@ import {
   buildSendAction,
   buildWsConnectOptions,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   isMessageEvent,
+  napcatInboundConversation,
+  napcatOutboundTarget,
   senderNickname,
   senderUserId,
   type NapCatEvent,
@@ -43,8 +45,6 @@ import {
   type NapCatWsSocket,
 } from './ws-types.js';
 
-const logger = getLogger('napcat');
-
 export interface NapCatWsEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
@@ -56,6 +56,8 @@ export interface NapCatWsEndpointOptions {
 }
 
 export class NapCatWsEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: NapCatWsEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
   readonly management: EndpointManagement = createNapCatEndpointManagement(this);
@@ -67,9 +69,10 @@ export class NapCatWsEndpoint implements EndpointInstance {
   #unregisterAgent?: () => void;
 
   constructor(options: NapCatWsEndpointOptions) {
+    this.#logger = getAdapterLogger('napcat', options.config.id);
     this.#options = options;
     this.#lifecycle = createEndpointLifecycle({
-      name: options.config.name,
+      name: options.config.id,
       // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
       reconnect: {
         initialIntervalMs: options.config.reconnect_interval,
@@ -82,7 +85,7 @@ export class NapCatWsEndpoint implements EndpointInstance {
 
   async start(): Promise<void> {
     if (this.#lifecycle.started) return;
-    this.#unregisterAgent = registerNapcatAgentEndpoint(this.#options.config.name, this);
+    this.#unregisterAgent = registerNapcatAgentEndpoint(this.#options.config.id, this);
     try {
       await this.#lifecycle.start((handle) => this.#connect(handle));
     } catch (err) {
@@ -118,15 +121,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({
+    this.#logger.debug(formatCompact({
       op: 'napcat_send',
-      endpoint: this.#options.config.name,
-      target,
+      endpoint: this.#options.config.id,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -326,31 +329,34 @@ 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,
+      sender: {
+        id: senderUserId(ev),
+        name: nickname,
+        ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+      },
+      endpointId: this.#options.config.id,
+      ...(mentioned ? { mentioned: true } : {}),
       metadata: Object.freeze({
         message_type: ev.message_type,
         user_id: ev.user_id != null ? String(ev.user_id) : undefined,
         group_id: ev.group_id != null ? String(ev.group_id) : undefined,
-        endpoint: this.#options.config.name,
         time: ev.time,
         self_id: ev.self_id != null ? String(ev.self_id) : undefined,
         role: ev.sender?.role,
         ...(nickname ? { nickname } : {}),
-        ...(mentioned ? { mentioned: true } : {}),
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'napcat_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -378,14 +384,14 @@ export class NapCatWsEndpoint implements EndpointInstance {
         if (settled) return;
         settled = true;
         if (!this.#options.config.access_token) {
-          logger.warn(formatCompact({
-            endpoint: this.#options.config.name,
+          this.#logger.warn(formatCompact({
+            endpoint: this.#options.config.id,
             ok: false,
             error: 'missing access_token',
           }));
         }
-        logger.debug(formatCompact({
-          endpoint: this.#options.config.name,
+        this.#logger.debug(formatCompact({
+          endpoint: this.#options.config.id,
           mode: 'ws',
           url: safeUrl,
         }));
@@ -404,7 +410,7 @@ export class NapCatWsEndpoint implements EndpointInstance {
 
       ws.on('message', (data) => {
         handleNapCatWsMessage(data, {
-          endpointName: this.#options.config.name,
+          endpointId: this.#options.config.id,
           pending: this.#pending,
           admit: (event) => this.admit(event),
         });
@@ -422,9 +428,8 @@ export class NapCatWsEndpoint implements EndpointInstance {
           : codeNum === 1006
             ? ' [abnormal]'
             : '';
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'disconnect',
-          endpoint: this.#options.config.name,
           code: codeNum,
           error: `${reasonStr || 'closed'}${codeHint}`,
           reconnect_ms: this.#options.config.reconnect_interval,
@@ -439,9 +444,9 @@ export class NapCatWsEndpoint implements EndpointInstance {
 
       ws.on('error', (err) => {
         const error = err instanceof Error ? err : new Error(String(err));
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'ws_error',
-          endpoint: this.#options.config.name,
+          endpoint: this.#options.config.id,
           ok: false,
           error: error.message,
         }));

package/src/ws-transport.ts

@@ -23,7 +23,7 @@ export function decodeWsPayload(data: unknown): string {
 export function handleNapCatWsMessage(
   data: unknown,
   options: {
-    readonly endpointName: string;
+    readonly endpointId: string;
     readonly pending: Map<string, NapCatPendingAction>;
     readonly admit: (ev: NapCatEvent) => void;
   },
@@ -50,7 +50,7 @@ export function handleNapCatWsMessage(
   } catch (error) {
     logger.warn(formatCompact({
       op: 'napcat_parse_failed',
-      endpoint: options.endpointName,
+      endpoint: options.endpointId,
       error: error instanceof Error ? error.message : String(error),
     }));
   }

package/src/wss-endpoint.ts

@@ -2,10 +2,10 @@
  * 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';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
@@ -18,9 +18,10 @@ import {
 import {
   buildSendAction,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   isMessageEvent,
+  napcatInboundConversation,
+  napcatOutboundTarget,
   senderNickname,
   senderUserId,
   type NapCatEvent,
@@ -39,8 +40,6 @@ import {
 } from './ws-types.js';
 import { verifyNapCatAccessToken } from './wss-auth.js';
 
-const logger = getLogger('napcat');
-
 export interface NapCatWssEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
@@ -49,6 +48,8 @@ export interface NapCatWssEndpointOptions {
 }
 
 export class NapCatWssEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: NapCatWssEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
   readonly management: EndpointManagement = createNapCatEndpointManagement(this);
@@ -62,6 +63,7 @@ export class NapCatWssEndpoint implements EndpointInstance {
   #unregisterAgent?: () => void;
 
   constructor(options: NapCatWssEndpointOptions) {
+    this.#logger = getAdapterLogger('napcat', options.config.id);
     this.#options = options;
   }
 
@@ -69,16 +71,16 @@ export class NapCatWssEndpoint implements EndpointInstance {
     if (this.#started) return;
     this.#started = true;
     this.#unregisterAgent = registerNapcatAgentEndpoint(
-      this.#options.config.name,
+      this.#options.config.id,
       this as unknown as NapCatWsEndpoint,
     );
     const handle = this.#options.http.ws(this.#options.config.path);
     this.#wsRelease = handle.onConnection((connection) => {
       this.#acceptConnection(connection);
     });
-    logger.info(formatCompact({
+    this.#logger.info(formatCompact({
       op: 'listen',
-      endpoint: this.#options.config.name,
+      endpoint: this.#options.config.id,
       mode: 'wss',
       path: this.#options.config.path,
     }));
@@ -115,9 +117,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,30 +141,33 @@ 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,
+      sender: {
+        id: senderUserId(ev),
+        name: nickname,
+        ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+      },
+      endpointId: this.#options.config.id,
+      ...(mentioned ? { mentioned: true } : {}),
       metadata: Object.freeze({
         message_type: ev.message_type,
         user_id: ev.user_id != null ? String(ev.user_id) : undefined,
         group_id: ev.group_id != null ? String(ev.group_id) : undefined,
-        endpoint: this.#options.config.name,
         time: ev.time,
         self_id: ev.self_id != null ? String(ev.self_id) : undefined,
         role: ev.sender?.role,
         ...(nickname ? { nickname } : {}),
-        ...(mentioned ? { mentioned: true } : {}),
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'napcat_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -189,7 +194,7 @@ export class NapCatWssEndpoint implements EndpointInstance {
     );
     socket.on('message', (data) => {
       handleNapCatWsMessage(data, {
-        endpointName: this.#options.config.name,
+        endpointId: this.#options.config.id,
         pending: this.#pending,
         admit: (event) => this.admit(event),
       });
@@ -203,8 +208,8 @@ export class NapCatWssEndpoint implements EndpointInstance {
         }
       }
     });
-    logger.debug(formatCompact({
-      endpoint: this.#options.config.name,
+    this.#logger.debug(formatCompact({
+      endpoint: this.#options.config.id,
       mode: 'wss',
       peer: connection.request.socket.remoteAddress,
     }));