@zhin.js/adapter-icqq 8.0.2 → 8.0.5

package/src/endpoint.ts

@@ -1,9 +1,14 @@
 /**
  * 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 { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { registerIcqqAgentEndpoint } from './icqq-agent-deps.js';
 import {
@@ -38,9 +43,9 @@ import {
 import {
   Actions,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundBody,
-  parseSendTarget,
+  icqqInboundConversation,
+  icqqOutboundTarget,
   type IcqqInboundMessage,
   type IpcEvent,
   type IpcResponse,
@@ -48,8 +53,6 @@ import {
 } from './protocol.js';
 import type { IpcFriendInfo, IpcGroupInfo, IpcMemberInfo, IpcSystemMessage } from './types.js';
 
-const logger = getLogger('icqq');
-
 /** Minimal IPC surface used by the endpoint (real IpcClient or test mock). */
 export interface IcqqIpcTransport {
   request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
@@ -84,6 +87,8 @@ export interface IcqqEndpointOptions {
 }
 
 export class IcqqIpcEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: IcqqEndpointOptions;
   readonly #createIpc: CreateIcqqIpc;
   readonly name: string;
@@ -126,8 +131,9 @@ export class IcqqIpcEndpoint implements EndpointInstance {
   #reconnectRunning = false;
 
   constructor(options: IcqqEndpointOptions) {
+    this.#logger = getAdapterLogger('icqq', options.config.id);
     this.#options = options;
-    this.name = options.config.name;
+    this.name = options.config.id;
     this.#createIpc = options.createIpc ?? defaultCreateIpc;
   }
 
@@ -145,18 +151,14 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     try {
       await this.#bindIpcSession();
       this.#unregisterAgent = registerIcqqAgentEndpoint(this.name, this);
-      logger.info(formatCompact({
-        op: 'connect',
-        endpoint: this.name,
-        mode: this.#options.config.rpc ? 'rpc' : 'ipc',
-        friends: this.friends.size,
-        groups: this.groups.size,
-      }));
+      this.#logger.info(
+        `connected (${this.#options.config.rpc ? 'rpc' : 'ipc'}) | friends: ${this.friends.size} | groups: ${this.groups.size}`,
+      );
     } catch (error) {
       await this.stop();
       // Startup connect failures are surfaced once (with stack) by AdapterIndex;
       // keep this at debug to avoid a duplicate error-level log.
-      logger.debug(`Failed to connect ICQQ IPC: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+      this.#logger.debug(`Failed to connect ICQQ IPC: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
       throw error;
     }
   }
@@ -195,10 +197,9 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         const jitter = Math.floor(Math.random() * 400);
         const delayMs = base + jitter;
         // 首次断开 WARN，后续重试静默为 DEBUG，避免刷屏
-        const disconnectLog = attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+        const disconnectLog = attempt === 0 ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
         disconnectLog(formatCompact({
           op: 'disconnect',
-          endpoint: this.name,
           ok: false,
           delay_ms: delayMs,
           attempt: attempt + 1,
@@ -207,17 +208,13 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         if (this.#intentionalDisconnect) break;
         try {
           await this.#bindIpcSession();
-          logger.info(formatCompact({
-            op: 'reconnect',
-            endpoint: this.name,
-            ok: true,
-            attempts: attempt + 1,
-            friends: this.friends.size,
-            groups: this.groups.size,
-          }));
+          this.#logger.info(
+            `reconnected after ${attempt + 1} attempt(s)`
+            + ` | friends: ${this.friends.size} | groups: ${this.groups.size}`,
+          );
           break;
         } catch (error) {
-          const retryLog = attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+          const retryLog = attempt === 0 ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
           retryLog(formatCompact({
             op: 'reconnect',
             endpoint: this.name,
@@ -262,10 +259,10 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     // 置空 ipc：start 前 / stop 后的 request() 走防御性报错而非 TypeError
     this.ipc = undefined as unknown as IcqqIpcTransport;
     this.#started = false;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  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 +271,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) {
@@ -305,17 +302,17 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }
     const resp = await this.ipc.request(action, params);
     if (!resp.ok) {
+      this.#logger.warn(
+        `send failed ${conversation.kind}:${conversation.id} | ${resp.error} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`,
+      );
       throw new Error(`发送消息失败: ${resp.error}`);
     }
     const messageId = String(
       (resp.data as { message_id?: unknown } | undefined)?.message_id ?? `sent_${Date.now()}`,
     );
-    logger.debug(formatCompact({
-      op: 'icqq_send',
-      endpoint: this.name,
-      target,
-      messageId,
-    }));
+    this.#logger.info(
+      `send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`,
+    );
     return messageId;
   }
 
@@ -348,7 +345,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         id: emojiId,
       });
       if (!resp.ok) {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'add_reaction',
           endpoint: this.name,
           message_id: messageId,
@@ -359,7 +356,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         }));
         return null;
       }
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'add_reaction',
         endpoint: this.name,
         message_id: messageId,
@@ -369,7 +366,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       }));
       return emojiId;
     } catch (error) {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'add_reaction',
         endpoint: this.name,
         message_id: messageId,
@@ -390,7 +387,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         id: emojiId,
       });
       if (!resp.ok) {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'remove_reaction',
           endpoint: this.name,
           message_id: messageId,
@@ -401,7 +398,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         }));
         return;
       }
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'remove_reaction',
         endpoint: this.name,
         message_id: messageId,
@@ -410,7 +407,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         ok: true,
       }));
     } catch (error) {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'remove_reaction',
         endpoint: this.name,
         message_id: messageId,
@@ -427,7 +424,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     try {
       const resp = await this.request(Actions.RECALL_MSG, { message_id: messageId });
       if (!resp.ok) {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'recall_message',
           endpoint: this.name,
           message_id: messageId,
@@ -436,14 +433,14 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         }));
         return;
       }
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'recall_message',
         endpoint: this.name,
         message_id: messageId,
         ok: true,
       }));
     } catch (error) {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'recall_message',
         endpoint: this.name,
         message_id: messageId,
@@ -630,13 +627,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({
+      this.#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;
     }
@@ -646,34 +644,33 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       content: msg.segments,
       rawMessage: msg.content,
     });
-    logger.debug(formatCompact({
-      op: 'icqq_inbound_admit',
-      endpoint: this.name,
-      id: msg.id,
-      target: msg.target,
-      sender: msg.sender,
-      channelType: msg.channelType,
-      mentioned: mentioned || undefined,
-      preview: msg.content.slice(0, 80),
-      segments: summarizeSegmentTypes(msg.segments),
-    }));
+    this.#logger.info(
+      `recv ${conversation.kind}:${conversation.id}`
+      + (msg.sender ? ` from ${msg.sender.name ?? msg.sender.id}` : '')
+      + (mentioned ? ' (mentioned)' : '')
+      + ` | ${truncatePreview(msg.content, 80)}`,
+    );
+    const quoteId = msg.metadata?.quote_id;
+    const { quote_id: _dropQuoteId, ...restMetadata } = msg.metadata ?? {};
     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,
+      endpointId: this.name,
+      ...(mentioned ? { mentioned: true } : {}),
+      ...(quoteId ? { replyTo: { id: String(quoteId) } } : {}),
       metadata: Object.freeze({
-        endpoint: this.name,
         channelType: msg.channelType,
-        ...msg.metadata,
-        ...(mentioned ? { mentioned: true } : {}),
+        ...restMetadata,
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
-        op: 'icqq_gateway_receive_failed',
-        target: msg.target,
+      this.#logger.warn(formatCompact({
+        op: 'recv',
+        endpoint: this.name,
+        target: `${conversation.kind}:${conversation.id}`,
+        ok: false,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -716,7 +713,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     if (!isIcqqMessagePostType(payload)) return;
     const data = payload as IcqqIpcMessageEvent;
     if (shouldSkipSelfInboundMessage(data)) {
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'self',
         endpoint: this.name,
@@ -727,7 +724,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }
     const normalized = normalizeIcqqInboundMessage(data);
     if (!normalized) {
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'normalize_failed',
         endpoint: this.name,
@@ -737,7 +734,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       return;
     }
     if (!this.#inboundDeduper.shouldProcess(normalized.messageId)) {
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'dedupe',
         endpoint: this.name,
@@ -747,14 +744,18 @@ 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,
       }),
       content: formatInboundContent(normalized.rawMessage),
       segments: normalized.content,
-      sender: normalized.userId,
+      sender: {
+        id: normalized.userId,
+        name: normalized.nickname || undefined,
+        ...(normalized.senderRole ? { roles: [normalized.senderRole] } : {}),
+      },
       channelType: normalized.channelType,
       metadata: buildIcqqQuoteMetadata(data, {
         nickname: normalized.nickname,
@@ -770,7 +771,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       payload as Parameters<typeof normalizeIcqqGuildInboundMessage>[0],
     );
     if (!normalized) {
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'guild_normalize_failed',
         endpoint: this.name,
@@ -779,7 +780,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }
     this.#guildCatalog.upsertFromInbound(normalized.raw);
     if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'icqq_inbound_skip',
         reason: 'dedupe',
         endpoint: this.name,
@@ -789,14 +790,14 @@ 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,
       }),
       content: formatInboundContent(normalized.rawMessage),
       segments: normalized.content,
-      sender: normalized.userId,
+      sender: { id: normalized.userId, name: normalized.nickname || undefined },
       channelType: 'channel',
       metadata: {
         guildId: normalized.guildId,
@@ -806,9 +807,9 @@ export class IcqqIpcEndpoint implements EndpointInstance {
   }
 
   /** 收件箱行公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
-  #inboxBase(): { adapter: string; endpointId: string } {
+  #inboxBase(): { adapter: string; endpointKey: string } {
     const id = String(this.#options.id);
-    return { adapter: id.split('\0').pop() ?? id, endpointId: this.name };
+    return { adapter: id.split('\0').pop() ?? id, endpointKey: this.name };
   }
 
   #recordInboxRequest(payload: Record<string, unknown>): void {
@@ -859,7 +860,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
         hooks.publish?.('endpoint:request', row);
       }
     } catch (error) {
-      logger.debug(formatCompact({
+      this.#logger.debug(formatCompact({
         op: 'inbox_pull_system_msg',
         endpoint: this.name,
         error: error instanceof Error ? error.message : String(error),
@@ -908,23 +909,8 @@ function toNumericId(value: number | string, label: string): number {
   return n;
 }
 
-function summarizeSegmentTypes(
-  segments: readonly { readonly type?: unknown }[] | undefined,
-): string | undefined {
-  if (!segments?.length) return undefined;
-  return segments
-    .map((segment) => {
-      if (typeof segment.type === 'string') return segment.type;
-      if (segment.type && typeof segment.type === 'object' && 'name' in segment.type) {
-        return String((segment.type as { name: unknown }).name);
-      }
-      return '?';
-    })
-    .join(',');
-}
-
 async function defaultCreateIpc(config: ResolvedIcqqConfig): Promise<IcqqIpcTransport> {
-  const uin = Number(config.name);
+  const uin = Number(config.id);
   if (config.rpc) {
     return IpcClient.connectRpc(config.rpc);
   }

package/src/icqq-agent-deps.ts

@@ -18,7 +18,7 @@ export interface IcqqAgentEndpoint {
 }
 
 export interface IcqqAgentDeps {
-  getEndpoint: (endpointId: string) => IcqqAgentEndpoint;
+  getEndpoint: (endpointKey: string) => IcqqAgentEndpoint;
   getAdapter?: () => { getEndpoint: (id: string) => IcqqAgentEndpoint };
 }
 
@@ -26,13 +26,13 @@ const endpoints = new Map<string, IcqqAgentEndpoint>();
 let override: IcqqAgentDeps | null = null;
 
 export function registerIcqqAgentEndpoint(
-  endpointId: string,
+  endpointKey: string,
   endpoint: IcqqAgentEndpoint,
 ): () => void {
-  endpoints.set(endpointId, endpoint);
+  endpoints.set(endpointKey, endpoint);
   return () => {
-    if (endpoints.get(endpointId) === endpoint) {
-      endpoints.delete(endpointId);
+    if (endpoints.get(endpointKey) === endpoint) {
+      endpoints.delete(endpointKey);
     }
   };
 }
@@ -42,9 +42,9 @@ export function setIcqqAgentDeps(deps: IcqqAgentDeps | null): void {
   override = deps;
 }
 
-function lookup(endpointId: string): IcqqAgentEndpoint {
-  const registered = endpoints.get(endpointId);
-  if (!registered) throw new Error(`Endpoint ${endpointId} 不存在`);
+function lookup(endpointKey: string): IcqqAgentEndpoint {
+  const registered = endpoints.get(endpointKey);
+  if (!registered) throw new Error(`Endpoint ${endpointKey} 不存在`);
   return registered;
 }
 

package/src/icqq-endpoint-commands.ts

@@ -4,7 +4,7 @@
  * ICQQ 的凭据由外部守护进程（@icqqjs/cli）按账号持有（~/.icqq/<uin>/），
  * 其 IPC/RPC 协议是「按 uin 连接 + auth + 账号级 action」，没有 add-account /
  * 触发 login 的 action——扫码登录只能经 `icqq login <uin>` CLI 完成。
- * 因此 add 不走 kv 凭据录入，而是 bindFlow：校验 uin、把 { name: '<uin>' }
+ * 因此 add 不走 kv 凭据录入，而是 bindFlow：校验 uin、把 { id: '<uin>' }
  * 追加到 plugins.icqq.endpoints，并引导用户先完成守护进程登录。
  */
 import { addEndpointToConfig, createEndpointCommands } from '@zhin.js/adapter';
@@ -17,18 +17,18 @@ export const icqqEndpointCommands = createEndpointCommands({
   running: (use) => use(icqqRuntimeStateToken).endpoints.values(),
   describeEntry: (entry) => (entry.rpc ? 'rpc（远程守护进程）' : 'ipc（本地守护进程）'),
   addDescription: '登记 ICQQ endpoint（uin 需先经 icqq login 完成扫码登录；重启 zhin 生效）',
-  bindFlow: ({ name }) => {
-    if (!name) {
+  bindFlow: ({ id }) => {
+    if (!id) {
       return '用法：icqq.endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
     }
-    if (!/^\d+$/.test(name)) {
+    if (!/^\d+$/.test(id)) {
       return 'icqq endpoint 名必须是纯数字 QQ 号（uin）';
     }
     try {
-      const filePath = addEndpointToConfig('icqq', { name });
+      const filePath = addEndpointToConfig('icqq', { id });
       return (
-        `✅ endpoint「${name}」已追加到 ${filePath} 的 plugins.icqq.endpoints。\n` +
-        `⚠️ 请确保已执行 icqq login ${name} 启动守护进程并完成扫码登录；重启 zhin 后生效。`
+        `✅ endpoint「${id}」已追加到 ${filePath} 的 plugins.icqq.endpoints。\n` +
+        `⚠️ 请确保已执行 icqq login ${id} 启动守护进程并完成扫码登录；重启 zhin 后生效。`
       );
     } catch (error) {
       return `添加失败：${error instanceof Error ? error.message : String(error)}`;

package/src/icqq-inbox.ts

@@ -11,7 +11,7 @@ import type { IpcSystemMessage } from './types.js';
 /** 行级公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
 export interface IcqqInboxBase {
   readonly adapter: string;
-  readonly endpointId: string;
+  readonly endpointKey: string;
 }
 
 /** post_type=request / request.* 判定（OneBot 事件壳）。 */
@@ -46,7 +46,7 @@ export function buildIcqqInboxRequestRow(
   const isGroup = requestType === 'group' || groupId != null;
   return {
     adapter: base.adapter,
-    endpoint_id: base.endpointId,
+    endpoint_id: base.endpointKey,
     platform_request_id: platformRequestId,
     type: isGroup ? 'group' : (requestType ?? 'friend'),
     scene_type: isGroup ? 'group' : null,
@@ -85,7 +85,7 @@ export function buildIcqqInboxNoticeRow(
   const targetId = userId != null && String(userId) !== String(actorId ?? '') ? userId : undefined;
   return {
     adapter: base.adapter,
-    endpoint_id: base.endpointId,
+    endpoint_id: base.endpointKey,
     platform_notice_id: platformNoticeId,
     type: noticeType,
     scene_type: groupId != null ? 'group' : null,
@@ -117,7 +117,7 @@ export function buildIcqqSystemRequestRow(
   if (!platformRequestId) return null;
   return {
     adapter: base.adapter,
-    endpoint_id: base.endpointId,
+    endpoint_id: base.endpointKey,
     platform_request_id: platformRequestId,
     type: kind,
     scene_type: kind === 'group' ? 'group' : null,

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(